Documenting command in Doxygen - c++

Question

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?

Answer 1

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 <you#you.net>
* #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
}