I have created a simple library in C++ and have with pretty good discipline documented the API in Doxygen. There are a few example programs to use the library in the package. Is there a trick to documenting those (as command-line programs) in the same Doxygen process?
2
-
You can create a MainPage.md and use Markdown to document those. That's typically how I do it.SimonC– SimonC2023-01-08 17:32:49 +00:00Commented Jan 8, 2023 at 17:32
-
1Shameless plug, but that's how I created the pages here: documentation.simonc.euSimonC– SimonC2023-01-08 17:33:24 +00:00Commented Jan 8, 2023 at 17:33
Add a comment
|
1 Answer
I've decided to add an answer to my comments with some more details.
As mentioned in my comments, I typically use the "MainPage" functionality of Doxygen.
For my public repositories, I use the README.md page and configure Doxygen as follows:
OUTPUT_DIRECTORY = docs/
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_PRIV_VIRTUAL = YES
EXTRACT_PACKAGE = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
INPUT = README.md <any other files or directories>
USE_MDFILE_AS_MAINPAGE = README.md
And then this generates the Doxygen HTML files and can be seen here, for example (excuse the shameless plug)
It's useful for providing a general overview of your library, use-cases and especially in your mentioned case, app arguments, switches, etc.
Edit 2023-01-10:
As mentioned in the comments under this answer, this is certainly not the only way of achieving OP's goal. If separate files (i.e. the executables) are to be documented, they can easily be added to the Doxyfile as such:
# individual files
INPUT = lib/include/myheader.hpp lib/src/myimpl.cpp examples/dosomethingcool.cpp
# Directories
INPUT = lib/include/ lib/src/ examples/
FILE_PATTERNS = *.cpp *.hpp
In your example implementation, you can then add a simple JavaDoc-style header:
/**
* @file myimpl.cpp
* @author Your Name <[email protected]>
* @date 2023-01-01
*
* @brief Contains an example of implementing/using my awesome library.
*
* Enter a detailed description of your reference implementation here.
* You may also include Markdown, so you can create simple tables,
* or format your text in a way that you like.
*
* Alternatively, you could also add an example using code.
* @code{.sh}
* # call my implementation like this:
* ./myimpl -LgTz100
* @endcode
*
* # A complete list of arguments:
* | Long opt | short opt | Description |
* |----------|-----------|-----------------|
* | -foo | -f | Foos something |
* | -bar | -B | Bars the baz |
*/
#include <iostream>
/**
* @brief Program entry point.
* You can continue with normal documentation here.
*
* @param argc The total amount of args passed
* @param argv The string arguments passed to the application
*/
int main(int32_t argc, char** argv) {
// implement whatever here
}
8 Comments
Evg
"Exit Codes" table is broken there.
James Howard
Yeah, and this works, but it does separate code from the documentation which is exactly what Doxygen was supposed to avoid.
SimonC
@Evg Thanks for pointing that out! Was fixed in the repo, but I forgot to update the docs.
SimonC
I'm not sure what you mean by it "separates the code from the documentation". You can always add the code files to your file input list. Unless I misunderstood you, you wanted to document the program usage, which is separate from the code in a sense.
James Howard
Yeah, I think I can work with that. I just wish it were more intuitive :)
|