please recommend doxygen shortcuts

Question

I have to write some code in C, so I decided to learn doxygen (and subversion).

I want my docs to be concise and reasonably unredundant. Best Tips for documenting code using doxygen? was helpful, but not enough. I need anti-redundancy suggestions.

is there a reference list of doxygen abbreviations with equivalents somewhere? sometimes a whole keyword seems to be needed, sometimes it seems to be inferred.

 /*! \fn int main(int argc, char *argv[])
  *  \brief the main function prototype
  *  \param argc  a counter to arguments
  *  \param argv  the arguments
  *  \return the program exit code
  */
 int main(int argc, char *argv[])

elsewhere

 /*! \fn int main(int argc, char *argv[])
  *  \details long explanation is that I just return 0
  *  \seealso main prototype
  */
 int main(int argc, char *argv[]) { return 0; }

has a lot of redundancy that needs to be kept in check over revisions. I have discovered some shortcuts, but this has been random. some in the above thread have claimed that \file is not needed, the doxygen manual suggests it is sometimes needed for global variables. /*!< is used after variables in structs */ which is a less redundant abbreviation of something longer, I presume (but I am not sure). Is \details necessary, or are longer comments after the \brief assumed to be details? some posts have stated that filenames are kept by the version control system, but my subversion manual does not mention doxygen, and my doxygen manual does not mention subversion.

I think /*!< ... */ just means that the documentation comment applies to the previous declaration, not the next one. It’s often used in struct definitions merely because it can be aesthetically nicer to have the documentation afterwards if the documentation can fit on the same line, but I’m pretty sure /*! ... */ can be used before a struct member and it’ll work just the same. — icktoofay
if we use /*! ... */ before, then how do we match it to individual parts of a structure? I wonder whether /*!< ... */ may also be better used to avoid the need for \param ?! — ivo Welch
@ivoWelch: You don’t use it before the entire structure; you use it before each member of the structure, e.g. struct person { /*! ... */ const char *name; /*! ... */ unsigned int age; }; — icktoofay

ivo Welch ivo Welch · Accepted Answer · 2014-06-22T18:16:57

So, here is what I have experimented with to obtain less doxygen name redundancy:

//! \file test.h  our very lonely .H file 

/*!
 * the file statements above are necessary, or doxygen will ignore the file.
 * Do not use the star-exclamation form following the file statements,
 *   or what follows is not picked up as a brief description. 
 */


/*!
 * \brief (I live in test.h) Here is a one-liner function description.
 * \return (I live in test.h) Here is an explanation of the return value
 */

int main(int argc,    //!<[IN] more information about argc---shows only in the .h file
     char *argv[]     //!<[IN] a text vector---shows only in the .h file
);

and

//! \file test.c  a very lonely .C file 

#include <stdio.h>
#include "test.h"  /*!< non-functional comment */


// if you use any doxygen code in front of the function, then doxygen will
// warn that the return code of function main() is not documented, even
// though it is.  So, the below will warn.


/*! 
 * \internal (I live in .C.)  This is how I work wonders.
 */

int main(int argc, char *argv[]) {
  printf("I am working wonders!\n");
  return 0;
}

In this way, the function name is prototyped once in the .h file and defined once in the .c file, both times in C. (This is a C language imposition, not doxygen's.) When written this way, doxygen is smart enough to pick up the function name by itself, and understand that the prototype and definition belong to one another. No \fn needed.

There is also no \param, with name-of-argument repetition, necessary, because doxygen is smart enough to pick it up right after the prototype definition.

The \return in .h remains necessary because I want it in my .h file, where I can check the meaning of the interface. It would have been even better if I could write //![RETVAL] after the ');' in the .h prototype but I could not find a way to do this. The again, return values are not named, so this is no big deal.

I have not fully grokked the \brief and \details formatting yet, but this is non-redundant enough now.

please recommend doxygen shortcuts

1 Answers