Comment a file in Doxygen

1
votes

I have a C header for which I want to write an introductory comment. Like this:

/**
 * @brief Provides stuff for my great program.
 */

#ifndef MYHEADER_H
#define MYHEADER_H

#define __USE_GLIBC

#endif

Furthermore, I have this Doxyfile:

FULL_PATH_NAMES = YES
TAB_SIZE = 8
OPTIMIZE_OUTPUT_FOR_C = YES
RECURSIVE = YES
INPUT = .
EXTRACT_ALL = YES
QUIET = YES
EXTRACT_STATIC = YES

When I run Doxygen now, it generates HTML and LaTeX documentation, but the brief description ends up documenting the macro instead of the whole file.

So how can I provide Doxygen with a brief description of the file?

3
cdoxygen

3 Answers

4
votes

You should use the @file macro to denote this comment related to the file as a whole:

/**
 * @file myheader.h
 * @brief Provides stuff for my great program.
 */
3
votes

Let's say your file is called header.h. Do this:

/*! @file header.h
 *  @brief Provides stuff for my great program.
 *
 *  Detailed description here, if any.
 */
2
votes

While using @file myfile.ext works in any file (ie. not just the one where the documentation comment is), according to the docs, doing just @file will document the current file.

Complete example

/**
 * @file
 * @brief A file that is documented.
 *
 * Detailed description, etc.
 */