Doxygen is not adding the documentation of any of my member functions in this class:
#ifndef SET_H_
#define SET_H_
/** #file */
/**
* A mathematical set
*/
class Set
{
virtual ~Set();
/**
* The countability of this set
* #returns Whether this set is a countable one or not.
*/
virtual bool isCountable();
...
}
#endif /* SET_H_ */
It produces the class documentation just fine, but not the function documentation even if I set EXTRACT_ALL to YES. Do you know why this is the case?
The function is private unless declared otherwise as public or protected.
By default, doxygen excludes private functions, even when setting EXTRACT_ALL is true. You can include them by adding to the Doxyfile EXTRACT_PRIVATE = YES.
Quoting from Doxygen's FAQ:
Is your class / file / namespace documented? If not, it will not be
extracted from the sources unless EXTRACT_ALL is set to YES in the
config file.
Are the members private? If so, you must set
EXTRACT_PRIVATE to YES to make them appear in the documentation.
Related
I wasn't able to show documentation for values of enum classes without setting EXTRACT_ALL. The comments for preserve, truncate and append aren't there. The enum itself is documented. If I enable EXTRACT_ALL I get a list.
My code is:
namespace grimoire
{
...
/// #brief Behaviour of function open_for_write for already existing files.
/// #see open_for_write()
enum class OpenMode
{
preserve = std::ofstream::out, /// Already existing file aren't opened.
truncate = std::ofstream::trunc, /// Discard existing contents.
append = std::ofstream::app /// Append to existing contents.
};
...
}
I'm using CMake to run Doxygen with:
#set(DOXYGEN_EXTRACT_ALL YES)
doxygen_add_docs(
docs
"${CMAKE_CURRENT_SOURCE_DIR}/include/grimoire"
"${CMAKE_CURRENT_SOURCE_DIR}/src")
Edit:
It doesn't even work with a classical enum and without explicit values. It looks like it has to do with my settings.
Solved:
I had to add a comment to the enclosing namespace. Doxygen extracted the enum itself and other stuff like functions and classes inside that namespace but not the enum entries.
Doxygen does not always pickup an enum, this can be overcome by means of using the \file command.
Furthermore you document the enum values after its definition, this means you should not use /// but ///<
So the limited example would looks like:
/// \file
/// #brief Behavior of function open_for_write for already existing files.
/// #see open_for_write()
enum class OpenMode
{
preserve = std::ofstream::out, ///< Already existing file aren't opened.
truncate = std::ofstream::trunc, ///< Discard existing contents.
append = std::ofstream::app ///< Append to existing contents.
};
Edit:
Based on the answer from OP, the given solution was not complete as the original problem was embedded in an namespace. To be able to show the enum in that case it is not sufficient to add the \file but it is also necessary the document the namespace. So a more complete example:
/// \file
/// The namespace documentation
namespace NS
{
/// #brief Behavior of function open_for_write for already existing files.
/// #see open_for_write()
enum class OpenMode
{
preserve = std::ofstream::out, ///< Already existing file aren't opened.
truncate = std::ofstream::trunc, ///< Discard existing contents.
append = std::ofstream::app ///< Append to existing contents.
};
};
I would like to generate a documentation of certain parameters that the Save-Method of various classes in my program generate. For that purpose, I would like to write a comment at the top of my save method, and these comments should go to a html and PDF file.
I would like to use doxygen to parse the source- and header files of my C++ project, however by default, doxygen generates a documentation for all the members and classes in my project, which is not what I actually want.
Is it possible to customize doxygen to generate documentation for only one single method which always has the same signature and Name (int Save();), and nothing else? How can that be achieved?
Have you looked at ENABLED_SECTIONS and the cond command? Here is a snippet of the example:
/// #cond DEV
/*
* The implementation of the interface
*/
class Implementation : public Intf
{
public:
void func();
/// #cond TEST
void test();
/// #endcond
/// #cond
/** This method is obsolete and does
* not show up in the documentation.
*/
void obsolete();
/// #endcond
};
/// #endcond
The output will be different depending on whether or not ENABLED_SECTIONS contains TEST, or DEV.
If this does not help, please clarify your question.
Is there a way to have doxygen show the documentation for individual private functions? I want doxygen to not show the documentation for the vast majority of private functions but show it for a select few private functions. My motivation is that these C++ private functions are provided to Python as extensions and I want their documentation to show up in Doxygen. However, I don't want them to be public because they are only needed by the classes themselves; they definitely belong in the private sector.
Thanks
I set the following in the config file:
EXTRACT_PRIVATE = YES
HIDE_UNDOC_MEMBERS = YES
This has the desired effect but will still show the documentation for all documented private members.
I then use #internal as the first line for the documentation of private members that I do not want to show.
Also, I can still document private members with a normal C++ comment. ie. dont use /** ... */ use /* ... */.
Usually I use a normal comment for member variables.
Finally, if I really want to show all that private documentation I can set:
INTERNAL_DOCS = YES
to create a more expansive version of the documentation.
The section between \cond and \endcond commands can be included by adding its section label to the ENABLED_SECTIONS configuration option. If the section label is omitted, the section will be excluded from processing unconditionally.
/** An interface */
class Intf
{
public:
/** A method */
virtual void func() = 0;
/// #cond COND1
/** A method used for testing */
virtual void test() = 0;
/// #endcond
};
See cond help
Not to see COND1 sections: just do not add it to ENABLED_SECTIONS configuration option.
There are a couple of ways to achieve this.
You could simply not document those functions that you don't want visible. By default, Doxygen will not show any members that you did not document. Thus, you can just tell it to show privates and any undocumented private members will not be shown.
Consider I have 2 header files.
// HEADER 1
/**
* Doc for Foo here?
*/
namespace Foo {
class This {...};
}
&&
// HEADER 2
/**
* Doc for Foo here?
*/
namespace Foo {
class That {...};
}
How should I handle this when documenting with Doxygen?
Maybe neither.
For example, imagine you have "<root>/utility/header1.hpp" which has its contents in namespace utility and "<root>/utility/header2.hpp" which does also.
You could add a file: "<root>/utility.hpp" which documents the utility namespace. You could put this at the top #error Documentation only. to make sure it's not accidentally included.
But I would recommend at least making some out-of-the-way file to keep it in a sane place (and not mixed in randomly with some class.)
I have placed documentation for namespaces that span multiple files into another file. My Doxygen builds use a separate file for the #mainpage tag. This forms the root of the built Doxygen, and is also a central location for such namespaces.
So I'll have project_name_mainpage.h, and in that file:
/**
#mainpage title
...whatever you want to tell the user about your application...
*/
/**
* #namespace your_namespace
* #brief An awesome description
* #details More sweet details
*/
Keeps it all in one place, and is relatively easy to find if you need to update it.
Find the best place for the documentation, whether it is in one of those files or another entirely. Use a comment block with Doxygen's namespace tag:
/**
* #namespace Foo
* Documentation for Foo here. More docs for Foo here,
* and down here.
*/
Docs here: http://www.doxygen.nl/manual/commands.html#cmdnamespace
Is it possible to document preprocessor defines in Doxygen? I expected to be able to do it just like a variable or function, however the Doxygen output appears to have "lost" the documentation for the define, and does not contain the define itself either.
I tried the following
/**My Preprocessor Macro.*/
#define TEST_DEFINE(x) (x*x)
and
/**#def TEST_DEFINE
My Preprocessor Macro.
*/
#define TEST_DEFINE(x) (x*x)
I also tried putting them within a group (tried defgroup, addtogroup and ingroup) rather than just at the "file scope" however that had no effect either (although other items in the group were documented as intended).
I looked through the various Doxygen options, but couldn't see anything that would enable (or prevent) the documentation of defines.
Yes, it is possible. The Doxygen documentation says:
To document global objects (functions, typedefs, enum, macros, etc),
you must document the file in which they are defined. In other words,
there must at least be a
/*! \file */
or a
/** #file */
line in this file.
You can use #defgroup, #addtogroup, and #ingroup to put related items into the same module, even if they appear in separate files (see documentation here for details). Here's a minimal example that works for me (using Doxygen 1.6.3):
Doxyfile:
# Empty file.
Test.h:
/** #file */
/**My Preprocessor Macro.*/
#define TEST_DEFINE(x) (x*x)
/**
* #defgroup TEST_GROUP Test Group
*
* #{
*/
/** Test AAA documentation. */
#define TEST_AAA (1)
/** Test BBB documentation. */
#define TEST_BBB (2)
/** Test CCC documentation. */
#define TEST_CCC (3)
/** #} */
Foo.h:
/** #file */
/**
* #addtogroup TEST_GROUP
*
* #{
*/
/** #brief My Class. */
class Foo {
public:
void method();
};
/** #} */
Bar.h:
/** #file */
/**
* #ingroup TEST_GROUP
* My Function.
*/
void Bar();
In this case, the TEST_DEFINE documentation appears in the Test.h entry under the Files tab in the HTML output, and the TEST_AAA etc. definitions appear under Test Group in the Modules tab together with class Foo and function Bar.
One thing to note is that if you put the file name after the #file command, e.g:
/** #file Test.h */
then this must match the actual name of the file. If it doesn't, documentation for items in the file won't be generated.
An alternative solution, if you don't want to add #file commands, is to set EXTRACT_ALL = YES in your Doxyfile.
I hope this helps!
In my "C" files, I use a comment format and #define line like this:
/** #brief Number of milli-seconds to wait*/
#define kTimeoutMSec (2)
My html documents do end up containing documentation I specify. (I do have #file at the top of the file and EXTRACT_ALL=YES)
Try setting EXTRACT_ALL option, I have that set in my project and it generates documentation for #defines. There might be a more elegant way of doing it without using EXTRACT_ALL so be sure to check the documentation
http://www.doxygen.nl/config.html#cfg_extract_all
Adding to the previous answers, it is also needed to have ENABLE_PREPROCESSING=YES on the Doxyfile.