Doxygen 1.10.0, Visual Studio Community 17.9.4, C++20 codebase.
I have been incrementally and successfully adding documentation code to the project. Everything's been good so far up the learning curve. I've just started introducing examples into the codebase and this is my first attempt. I have the following function whose documentation output, pre-example insertion, is as expected:
/*! \brief A function to return the name as a string
The function retrieves the name string from a vector of names. The index into the vector is the object's data member.
If the input parameter is not provided, the default is the name vector containing the standard names.
\param [in] Strings is a vector containing name strings.
\return The current name as a string.
\exception out_of_range exception thrown if String's bounds are exceeded. This indicates that either the vector doesn't have enough elements or the month number is out of range.
*/
std::string WxM::GetCurrentString(const std::vector<string>& Strings) const
{
// code removed for brevity
}
Without any example command, the documentation is correctly contained and properly formatted on the HTML output page under the Classes > Class List > WxM > GetStringName() page.
\example{lineno} GetCurrentString_Example.cpp
This is an example of how to use the GetCurrentString function.
main()
{
std::vector<std::string> Names = { "Test", "Test Again", ... };
WxM WxMInstance;
// current now contains the name.
std::string current = WxMInstance.GetCurrentString(Names);
}
Doxygen reports no errors or warnings related to the example.
I expected the example code to be displayed in the output HTML under its own heading on the function's documentation page, after the function's signature, \brief and main descriptions, and the \param, \return and \exception texts, and before the Definition location reference and caller graph.
The function's page now contains only the function signature, an Examples header with a reference to the example, and the "Definition at.." location reference and caller graph. The remaining text has disappeared. However, all the text, including the sample code, appears when I follow the example link which takes me to the new main menu Example category.
How do I retain the previous style (the function description on its own page) and list the example code on that page? Is this the default behaviour?
The Doxygen \example example is not particularly helpful or rich enough to provide insight. I've Googled for any clues and submitted the question to a coding AIChat, but this is pretty specific question. I've found little that addresses this topic.
I was able to reproduce the problem you described, and I think I have a solution to your need: use the \include directive, instead of \example.
I've taken the liberty of adding a class around your code example, just to get a minimally compilable example:
// WxM.h
#include <string>
#include <vector>
/*! \brief The WxM class
*/
class WxM {
public:
/*! \brief A function to return the name as a string
The function retrieves the name string from a vector of names. The index into the vector is the object's data member.
If the input parameter is not provided, the default is the name vector containing the standard names.
\param [in] Strings is a vector containing name strings.
\return The current name as a string.
\exception out_of_range exception thrown if String's bounds are exceeded. This indicates that either the vector doesn't have enough elements or the month number is out of range.
\b Example
\include GetCurrentString_Example.cpp
*/
std::string GetCurrentString(const std::vector<string>& Strings) const
{
return "Hello, world!";
}
};
Note specifically \include GetCurrentString_Example.cpp instead of \example GetCurrentString_Example.cpp.
\include <file> has the effect of embedding your specified file "inline" within the "scope" of the current documentation, whereas \example <file> seems to have the effect of creating a link to your specified <file>.
You've already read the Doxygen documentation, obviously, but for future readers who stumble into this answer, the \example documentation is here, and the \include documentation is here.
Doxygen provides an example of how \example renders here, which is in line with our observation. So, far as I can tell, what we've observed is the default and only possible behavior from \example.
\example requires you to specify EXAMPLE_PATH in your Doxyfile, which you noted you've already done, so there should be nothing else you need to add/edit in your Doxyfile.
The explicit blank line after \exception appears necessary. Without it, the bolded word Example appears in the same paragraph as the \exception content.
(My conjecture: I suspect the explicit blank line is because of how Doxygen separates between different "categories" of commands.
Note that \example, \include, etc. are in a "--- Commands for displaying examples ---" section of the Doxygen documentation, while \b is in a "--- Commands for visual enhancements ---" section.
I might intuit that even with only a single carriage return between \return and \exception, it would be "clear" to Doxygen that the only reasonable behavior would be to separate those two commands' content into separate paragraphs, whereas perhaps a single carriage return between a command's content and more content (including a visual-enhancement command) is implicitly concatenated into the same paragraph. For example, the author might simply want to honor a right-margin as he's writing \exception's content.)
The \include directive seems to honor the {lineno} option, so \include{lineno} GetCurrentString_Example.cpp will include the content of that file with line numbers on the left.
Last: as you noted in your comment, \snippet['{'option'}'] <file-name> is another viable option, with rendering differences vs. \include documented here.