I'm working on a project that uses multiple libraries, set up in a structure like so:
/src
/libs/libOne
/libs/libTwo
I want to generate a single Doxygen page which covers all my code as well as the libraries. This was quite simple by just pointing Doxygen at the root. However, I want the doxygen output to be grouped so I can clearly see which library each class/file belongs to. However, since the libraries are not written by me I don't want to change them to add \addtogroup comments.
I don't mind if the produced documentation is subpar for the libraries (for example if they don't include doxy compatible comments), I still want them included so I can view call graphs, and quickly browse the classes, etc.
How can I group each libraries code into modules without changing the libraries' source?
thanks
You should put all the necessary documentation in external files. I didn't know how to do this, but I've tried to set up a minimal environment like yours and it worked well. Just for documenting something I've grabbed the example code on the Doxygen site:
test1.h:
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);
and wrote the totally useless test2.h (just to have two different files...):
void itdoesnothing();
Here comes the nice part. I've made an external header just for documenting the above, called it test_doc.h (again, just used the example on the Doxygen site):
/*! \addtogroup everything The main group
This group contains everything.
#{
*/
/*! \file test.h
\brief A Documented file.
Details.
*/
/*! \def MAX(a,b)
\brief A macro that returns the maximum of \a a and \a b.
Details.
*/
/*! \var typedef unsigned int UINT32
\brief A type definition for a .
Details.
*/
/*! \addtogroup err Error handling
Error handling related stuff
#{
*/
/*! \var int errno
\brief Contains the last error code.
\warning Not thread safe!
*/
/*! #} */
/*! \addtogroup fdrelated File description related
File descriptor related stuff.
#{
*/
/*! \fn int open(const char *pathname,int flags)
\brief Opens a file descriptor.
\param pathname The name of the descriptor.
\param flags Opening flags.
*/
/*! \fn int close(int fd)
\brief Closes the file descriptor \a fd.
\param fd The descriptor to close.
*/
This successfully documented both files for Doxygen. This way you can group files, namespaces etc. too, as stated in the manual:
Members of a group can be files, namespaces, classes, functions, variables, enums, typedefs, and defines, but also other groups.
So try reading http://www.doxygen.nl/grouping.html too and see what's possible to do with the things I've mentioned above. Good luck!
Related
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 ?
Is it possible to tell Doxygen to expand macros but ignore other preprocessor directives?
Take the following into account:
#if defined(linux)
#define OS_LINUX
int function() { /* ... */ }
// Other functions defined for Linux
#elif defined(__WIN32__)
#define OS_WINDOWS
int function() { /* ... */ }
// Other functions defined for Windows
#else
#error "OS unsupported."
#endif
In this case, I want the functions for both Windows and Linux to show up, but I also want the macros OS_LINUX and OS_WINDOWS to show up in the documentation as well. Is there a way to document both macros while ignoring the #ifs?
No, you cannot do that you will have to build the documentation for each configuration separately. However if both Windows and Linux have the same interfaces defined, the documentation will surely be the same for both functions in any case?
By default if Doxygen finds documentation for a declaration in a header and documentation for corresponding definitions in source-files, the documentation in the header will be used. In this case you can use this to your advantage by only placing Doxygen mark-up in the header files. Normally the interfaces will be identical cross-platform and you will have a single header, but multiple implementations for each platform, either in separate sources or using conditional compilation.
I currently have a couple of #define in c files that turn off some functionality to hardware for testing. However, I want to document them with doxygen when they are undefined as well.
For example:
This works fine:
/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
#define SIMULATE_SOME_HW_INTERFACE
When you change the #define to #undef, you get a warning in doxygen, and it doesn't show up in the doxygen generated output. I want to document this #define wether it's defined or undefined.
How can I force doxygen to document a #undef???
Define them in a header file that is only included by Doxygen (put in a separate directory tree from the main source).
Guard this header file by wrapping it with a define that you only define in the Doxygen setup, eg:
#ifdef ONLY_FOR_DOXYGEN
/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
#define SIMULATE_SOME_HW_INTERFACE
#endif
I have used this to also conditionally include lightweight class definitions for things like MFC base classes so they appear as bases for the class hierarchy without having to parse all of MFC.
I found a kludgy way by adding the #undef under the #define. This way it's defined for Doxygen, but immediately undefined for the compiler.
/// \def SIMULATE_SOME_HW_INTERFACE
/// Define this when you want to simulate HW interface.
/// Comment out #undef to simulate HW interface
#define SIMULATE_SOME_HW_INTERFACE
#undef SIMULATE_SOME_HW_INTERFACE
I was trying to figure out how to set SIMULATE_HW_INTERFACE in the Doxyconfig file using PREDEFINED option. Couldn't get it to work. So here's my best solution so far.
I solved my problem with documenting compilerflags like this in the main headerfile:
/**
* \defgroup flags Compilerflags
*/
/**
* \def MY_FLAG
* \ingroup flags
* Dokumentation....
*/
#ifndef MY_FLAG
#define MY_FLAG
#undef MY_FLAG
#else
#define MY_FLAG
#endif
This way everything works fine: doxygen and compiling and you can keep specifying your flags in commandline...
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.
I am building a Qt based project, and many Qt classes are found in the target documentation.
How can I tell Doxygen to disable documentation generation for some classes? For Q.*?
Working under the assumption that what you have is something like this: (The question is a little unclear in this regard)
/**
* Some documentation for class X
*/
class X: public osg::Drawable {
...
}
And your problem is that you want to include documentation for class X, but not for class osg::Drawable, the proper technique is to use EXCLUDE_SYMBOLS. For example, in the case above use
EXCLUDE_SYMBOLS = osg::Drawable
If you want to be slightly more rigorous, you can use
EXCLUDE_SYMBOLS = osg::Drawable \
Drawable
Wild-cards are also allowed, so this will also work
EXCLUDE_SYMBOLS = osg::*
If \internal tag does not work, you can try \cond ... \endcond tags for marking a portion of code to be hidden from Doxygen.
EDIT
If you want to exclude specific files, you can use EXCLUDE_PATTERNS variable in Doxyfile configuration file.
Its not the best way but one can mark some portion of the documentation (class, members, ...) with the private. This prevents the piece of code from being included in the output documentation. (I use this to hide copy/move constructors/operators from appearing in the API documentation.)
/*!
* \brief This is included.
*/
class API
{
public:
/*!
* \brief So is this.
*/
API() noexcept;
/// \private
~API() noexcept; /* But this not, though technically public. */
private:
int m_version; /* This is not either. */
}
One should note though that this is a Doxygen extension for PHP, which according to the documentation they should not be used.
For PHP files there are a number of additional commands, that can be used inside classes to make members public, private, or protected even though the language itself doesn't support this notion.
The other option is to use the solution mouviciel provided, but it requires at least two lines.
Though not the correct answer for the detailed question it might be helpful for readers of the question title (like me). It works for classe too!