I am trying to figure out how I can detect if a C source file contains a list of custom doxygen sections.
For instance, I want that each C source file contains:
/**
\section limitations Limitations
The limitations ...
\section choices Choices
The design choices ...
*/
As I use doxygen to document the code, I would like doxygen prints a warning if those sections are missing. Is it possible ?
Related
We use Doxygen to generate the API and related documentation for our software library. The library is written in C++, exposes a C interface, and includes wrappers for other languages like C# and Python.
Much of the wrapper languages use the same names for structures/classes as the C API. When Doxygen finds one of them it always links to the C structure. I believe I read somewhere this is by design--it links to the first one that was found. How can I get Doxygen to link the one for a particular language? Ideally to also have the generated link only show the structure/class name (ie. not have some prefix).
Very basic example with pseudo-code in case it helps:
C++ pseudo-code:
ConfigurationOptions.h:
/// Data container
struct ConfigurationOptions
{
}
Bar.h:
/// Class to manage ...
class Bar
{
/// Construct object based on specified options.
///
/// \param options
/// A ConfigurationOptions object with ...
Bar(const ConfigurationOptions & options);
}
Python pseudo-code:
ConfigurationOptions.py:
## Data container
class ConfigurationOptions(structure):
def __init__(self):
self.count = 10
Bar.py:
## Class to manage ...
class Bar:
## Construct object based on specified options.
## See ConfigurationOptions documentation.
##
## \param options [ConfigurationOptions]
## A ConfigurationOptions object with ...
def __init__(self, options):
When both files are included in the Doxygen configuration, it will auto-link all references to ConfigurationOptions to the C++ struct ConfigurationOptions. I want the Python documentation to link to the Python objects.
To be clear, using this example, I want the references to ConfigurationOptions in Bar.py (lines 4, 6, 7) to link to the Python ConfigurationOptions, not the C++ one.
I've found a way to do it (at least with Python) by prefixing the element with the name of the Python module (file).
For example:
## \param options [ConfigurationOptions.ConfigurationOptions]
## A ConfigurationOptions.ConfigurationOptions object with ...
But there's downsides to this, and I don't know if it'll work with the other languages.
The problem looks related to the version used, when I use the 1.8.17 version and the current version (1.9.5) I get as class list:
Though when I use the current master version (Doxyfile 1.9.6 (28ec5dc5a74e0b2cbf66ea0fde2696f9c5c340be)) I get:
So it looks to me that there is in the current master a better separation between the python and the C++ part (the python part show though the artificial namespace).
It has to be checked whether or not the links are al correct.
Edit
Regarding the extra problem of the links from python that should link to python I see the following possibilities:
use full qualified names so for ConfigurationOptionsuse ConfigurationOptions.ConfigurationOptions
see to it that the C++ code is embedded into a namespace (maybe conditional just for the documentation (see the doxygen commands like \cond or use preprocessor commands for it).
The company I'm working for does not use Doxygen, and in their coding standard explicitly prohibits "parseable comment styles such as javadoc, etc".
However, I've still found it very useful to run Doxygen myself just so I can see the class structure, and get nice per-class documentation of all the methods the a class has, including inherited ones.
The company does document the classes in the header files, with simple comments above each method declaration. It would be very useful if I could configure Doxygen to treat these comments as the function descriptions, even though they don't start with any Doxygen markers.
So: is it possible to get Doxygen to treat comments on the line above declarations as if they are the description for that item even when the comment is not marked with Doxygen's "parse this comment" markers?
The next best thing is to click on the #include <foo.h> links at the top of the class file to jump to the file itself, which I have been using. That doesn't help for seeing all of a derived class's methods in one place, though.
When the comments above the methods have only "normal" comments i.e. with /* or // the best thing to do would be that you write a small filter (see e.g. INPUT_FILTER with sed or awk or ... ) in which you convert (all?) /* / // comments into /** / /// so the comment blocks are parsed by doxygen. The result is not as nice as with "full" doxygen comments.
It is just a workaround and can lead to unexpected results when the INPUT_FILTER does not exclude e.g. // inside strings from consideration.
I would like to change the page layout for a single source file. The other pages should be generated as before.
Other option would be to generate a seperate page referencing the relevant content from that source file.
To make it a little more concrete, I have the following file and would like to generate a documentation file only including these comments without the printing of includes, etc.
And as said this behavior is only intended for this single source file.
/**
* TreeNode
*xxx
*/
class TreeNode
/**
* TreeNode2
*xxx
*/
class TreeNode2
Thanks a lot!
I think your best approach is to exclude the bits you don't want by surrounding those parts in the file with #cond and #endcond markers. (The #if 0 of doxygen.)
In that way your file processing won't be complicated with file-specific layouts (which I'm not sure is possible anyway) and the 'special' handling of that file is visible within that file's content.
I commented my source file with doxygen syntax, example:
/**
* #brief get Root tree
*/
void get() {}
Now I want to get the function's brief message by doxygen's API, who can help me how to do it?
I find the best way to get access to this kind of information is to generate XML file using Doxygen and then use your favorite XML parsing library to access it.
The XML output is the preferred way to extract information gathered by doxygen.
You can use your favorite XML parser or download doxygen source package and look in addon/doxmlparser for a C++ API to interface with doxygen's XML output. This parser is optimized to deal with the potentially large amount of XML output produced by doxygen in an efficient way.
As an alternative you can also directly interface with doxygen's internals. For an example look at addon/doxyapp in the source package. Note this is a more volatile interface and that with this approach you are bound to the terms of the GPL v2.
I am trying to use Doxygen Automatic link generation to document some enum types. However, it is not generating links for the global enum types. It does generates links for the global struct types. Is there something I am missing? I am using the example provided on the link above. As required, I have documented the file in which the types are defined.
update1: I am using Doxygen version 1.6.3
update2: global structs are ok
Yeah, I had that same issue; i think doxygen thinks they are private or something stupid like that. Try using the \public. Don't forget to do the /*! on the first line
/*! \public
* Enum description goes here
*/
typedef enum {
/**
* Printer control language ZPL
*/
PRINTER_LANGUAGE_ZPL,
/**
* Printer control language CPCL
*/
PRINTER_LANGUAGE_CPCL
} PrinterLanguage;
I was having the same issue. Some header files generated a link for enums and other header files did not. You must explicitly document the file.
Here is a excerpt from this page int the documentation.
http://www.doxygen.nl/manual/docblocks.html#memberdoc
To document a global C function, typedef, enum or preprocessor
definition you must first document the file that contains it (usually
this will be a header file, because that file contains the information
that is exported to other source files).
Attention
Let's repeat that, because it is often overlooked: 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.