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
Related
Can I use an existing code range (means some lines of code from a cpp file) as example in the doxygen docu?
/*!
* \brief My Foo class
* \details More about foo
* \example?? Foo used like here, some LOC from cpp follow (how can I do that??)
*/
class Foo
I want to show 3-10 lines of existing code of how I have used Foo. Those 3-10 line are supposed to come from a cpp file.
I understand that I have to tag the very cpp file with \file, but how do I refer to some lines of code there?
Something like this (incorrect pseudo code, as I have no idea how to do it)
somewhereelse.cpp
...
...
//! \example Foo (supposed to display with Foo docu). This is how Foo is used
//! #{
Foo f;
f.init(); // init first
f.start(); // then start
//! }#
...
As pointed out by albert (comments above) \snippet can be used. A full example can be found here https://stackoverflow.com/a/16034375/356726
You refer to a file and in that file (.cpp in my scenario) you mark the block by [] brackets. It then will appear as code block.
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.
I am sure this is something silly I've done but I can't see what it is:
So I have c++ project which has a main.cpp file and some classes. It was not written with doxygen in mind (error #1) but I'm looking to correct my mistake and generate some documentation. So I installed doxygen and ran the doxygen GUI, entered the project name/synopsis and specified the source and destination locations.
Also to get some output above a function I added a comment in the style the doxygen spec requires:
//! My actual function doesn't really look like this
/*!
* Some sample detail which isn't exactly the same as the main
* function but the structure is the same
*/
void sampleFunction()
{
doSomethingUninteresting();
}
However when I hit run in doxywizard no extra comments are made.
If I set the extraction mode to documented entities only main.cpp doesn't even show up. If I set it to all entities main.cpp appears under files and the function is in there however there is no detail whatsoever in the file.
As a complete novice trying to retrofit my project no doubt I've omitted to do something important but all the documentation/tutorials I've read don't suggest anything other than what I've stated needs to be done so I turn to the knowledgeable SO community for assistance
UPDATE:
In response to the comment by Arne Mertz here are a few more details:
Doxywizard is in Program Files/doxygen/bin and the config file is wherever doxywizard creates it by default
My source code is in User/Desktop/
The output folder is in User/Desktop/Documentation
To document a global functions you have also to include a file name. E.g.
/*!
* \file MyFileName.cpp
* \brief a brief description of a file
*/
//! My actual function doesn't really look like this
/*!
* Some sample detail which isn't exactly the same as the main
* function but the structure is the same
*/
void sampleFunction()
{
doSomethingUninteresting();
}
Note, that the name after \file keyword should be exactly as the name of the file.
I was being foolish as I suspected, to be safe I'd made a copy of my project and so the version I was editing was not the version being interpreted by doxygen
I apologise to anyone who wasted their time trying to help with this but I very much appreciate your attempts to do so :)
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.
I'm having issues with Doxygen recognizing namespaces and modules. I believe the issue surrounds whether to place the \addtogroup within the namespace or outside the namespace.
Example 1, outside the namespace:
/*!
* \addtogroup Records
* #{
*/
//! Generic record interfaces and implementations
namespace Records
{
//! Describes the record interface
class Interface;
} // End namespace Records
/*! #} End of Doxygen Groups*/
Example 2 - within namespace
//! Generic record interfaces and implementations
namespace Records
{
/*!
* \addtogroup Records
* #{
*/
//! Describes the record interface
class Interface;
/*! #} End of Doxygen Groups*/
} // End namespace Records
I would like the namespace Records to appear under the Doxygen Namespaces tab and indirectly under the Modules tab. Clicking on the item in the Namespaces page should produce a page containing Records::Interface. Clicking on the item in the Modules tab should also produce a page containing Records::Interface.
In my Doxygen documentation, I have items missing from Namespaces tab that are in Modules and vice-versa, due to my inconsistency resulting from this dilemma.
So which is the proper method, Example 1 or Example 2?
{The Doxygen manual is not clear on this topic.}
Doxygen: \addtogroup
Doxygen: documenting namespaces
I have performed an experiment using Doxygen and the two examples and here are the results.
The class names in the examples have been renamed to avoid confusion with Doxygen.
Example 1, Outside Namespace
/*!
* \addtogroup Records
* #{
*/
//! Generic record interfaces and implementations
namespace Records
{
//! Describes the record interface
class Interface;
} // End namespace Records
/*! #} End of Doxygen Groups*/
Doxygen Results:
Click on Modules button (in the main bar).
Click on "Records" module in the window.
Example 2: Within Namespace (class renamed to Fields)
//! Generic record interfaces and implementations
namespace Fields
{
/*!
* \addtogroup Fields
* #{
*/
//! Describes the record interface
class Interface;
/*! #} End of Doxygen Groups*/
} // End namespace Fields
Doxygen Results:
Click on Modules button (in the main bar).
Click on "Records" module in the window.
Summary
The location of Doxygen \addtogroup command has different results depending on whether it is located within a namespace definition or outside. When declared outside of a namespace, the Doxygen Modules tab will show the namespace, as shown in Example 1 above. When the \addtogroup command is placed inside a namespace, the Doxygen Modules tab will not display the namespaces as shown in Example 2 above. If you want your namespace to be listed in the Doxygen Modules tab, locate the \addtogroup command outside of the namespace.
As an alternative, you could also use \ingroupRecords in the namespace documentation:
/**
* \defgroup Records Title for records module
* #brief Short doc of Records
*
* Long doc of Records.
*/
/**
* #brief Generic record interfaces and implementations
*
* \ingroup Records
*/
namespace Records {
/// Describes the record interface
class Interface;
} /* namespace Records */