I have a file like:
/** #file some description */
void SomeFunc();///< brief function description
The #file keyword is needed to document global functions, as per Doxygen mailing list. So here it is, but Doxygen keeps ignoring SomeFunc(), i.e. it doesn't appear anywhere in documentation.
The #file keyword is used to specify the file name, not the description. Try something like this:
//!
//! #file filename.h
//! #brief some description
//!
Related
My doxygen for the following code shows up like this:
Spawns two mettaurs on the fieldMay optionally spawn an empty tile for challenge
Where the brief description should be. Notice it's merging the brief and the detailed description.
/*! \brief Spawns two mettaurs on the field
* \class TwoMettaurMob
*
* May optionally spawn an empty tile for challenge
*/
#pragma once
#include "bnMobFactory.h"
#include "bnMettaur.h"
#include "bnMettaurIdleState.h"
class TwoMettaurMob :
public MobFactory
{
public:
TwoMettaurMob(Field* field);
~TwoMettaurMob();
/**
* #brief Builds and returns the mob
* #return Mob pointer. must be deleted manually.
*/
Mob* Build();
};
I'm following doxygen's example for doc blocks:
/*! \brief Brief description.
* Brief description continued.
*
* Detailed description starts here.
*/
Anyone know a solution?
I could reproduce the problem with the current (1.8.15) version of doxygen.
The solution of #Someprogrammerdude does work
The order of commands is a bit strange I would have expected first the \class followed by the \brief description, also the \class is not necessary as the documentation is (in this case) directly in front of the class.
Another solution is to place a . at the end of the sentence and have JAVADOC_AUTOBRIEF or QT_AUTOBRIEF set to YES.
The background of the problem is that \class is not seen as a ending the \brief documentation. It might be worthwhile to submit an issue report at https://github.com/doxygen/doxygen/issues/new (so either it can be fixed or some extra objections can be given against using \class, and others with similar meaning, for terminating a brief description.
I intend to include some documented C++ classes (let say AClass) within a Doxygen group (let say GROUP_C), while that group is into another one (let say GROUP_B), and that second group into another, base one (let say GROUP_A). Like this:
/** \addtogroup GROUP_A */
/** #{ */
/** \defgroup GROUP_B */
/** #{ */
/** \defgroup GROUP_C */
/** #{ */
/// Comment
class AClass
{
};
/** #} */
/** #} */
/** #} */
I'm trying to get a clean and logical documentation for that situation, but, as simple as I see it, I have not been able to found anything more specific than the Doxygen official documentation, where nothing is said about any cyclical grouping problems. However, just doxygen-ing the simple code above, such problems occur:
warning: Refusing to add group GROUP_C to group GROUP_B, since the latter is already a subgroup of the former
I also get strange breadcrumbs indications of the generated module under the AClass documentation:
Does anybody know what am I understanding wrong in the nesting-group system of Doxygen?
Thanks in advance!
This solution has been working for me for many years since old versions of Doxygen:
/** \defgroup GROUP_A My top-level group description
*
* Put here a longer description.
*
**/
/** #addtogroup GROUP_B My group B description
* \ingroup GROUP_A
* #{ */
// classes, etc.
/** #} */
/** #addtogroup GROUP_C My group C description
* \ingroup GROUP_B
* #{ */
// classes, etc.
/** #} */
Unfortunately your given example works as expected on doxygen-1.8.8 and on latest master git branch. The warning does not appear.
Is it possible you are including other source files (than the presented example code) into your test run and that other files contain conflicting \defgroup or \addgroup statements that cause the circles in the group structure?
Regarding that "GROUP_A" doubling line below "AClass Class Reference" - I guess that is simply a doxygen bug.
I am trying to add a function to multiple groups but it does not seems to be working.
I followed the instructions from here
Here are the comments I added:
/**
* \defgroup version1 version 1
*/
/**
* \defgroup version2 version 2
*/
/**
* \ingroup version1 version2
*/
BOOL CLoginFormDlg::OnInitDialog(){}
The function only appears in the version2 module and not in the version1 module.
if I write version1 last like this:
/**
* \ingroup version2 version1
*/
BOOL CLoginFormDlg::OnInitDialog(){}
then the function only appears in the version1 module and not the version2 module.
I would like them to appear in both modules
The link you provided includes a paragraph that explains why it doesn't work:
Note that compound entities (like classes, files and namespaces) can be put into multiple groups, but members (like variable, functions, typedefs and enums) can only be a member of one group (this restriction is in place to avoid ambiguous linking targets in case a member is not documented in the context of its class, namespace or file, but only visible as part of a group).
One approach to consider to solve this problem might be to create different Doxygen projects for each version of your code. You would create a Doxyfile for each version.
In this case, instead of trying to include common code in both sets of documentation using the \ingroup command, you would be excluding unrelated code from each set using conditional sections delimited by either \if...\endif or \cond...\endcond.
So in your version1 module, you would do the following:
/**
* \if _VERSION1_
*/
<all code in your version1 module>
/**
* \endif
*/
and in your version2 module:
/**
* \if _VERSION2_
*/
<all code in your version2 module>
/**
* \endif
*/
Code that needs to appear in both modules, such as your BOOL CLoginFormDlg::OnInitDialog(){} function, would have no such conditional commands, so would be included in both sets of documentation.
In your version1 Doxyfile, add the following line:
ENABLED_SECTIONS = _VERSION1_
and in your version2 Doxyfile:
ENABLED_SECTIONS = _VERSION2_
To link your version1 and version2 documentation sets together, you can use Doxygen's tag file mechanism.
See also
\cond
\if
ENABLED_SECTIONS
Tag files
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 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.