Question

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

Answer 1

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!