1

No documentation is generated for any of the functions for my C repo

My configuration:

# Difference with default Doxyfile 1.9.1
PROJECT_NAME           = WLib
OUTPUT_DIRECTORY       = doxy
OPTIMIZE_OUTPUT_FOR_C  = YES
EXTRACT_ALL            = YES
CASE_SENSE_NAMES       = NO
HIDE_SCOPE_NAMES       = YES
INPUT                  = .
FILE_PATTERNS          = *.c \
                         *.h
RECURSIVE              = YES

Edit the code:

/** \fn     Array Fill
 *  \param  sa  size of the array A in bytes
 *  \param  a   the array A
 *  \param  sb  size of the array B in bytes
 *  \param  b   the array B
 *  \brief  Takes two arrays and their sizes. Fills the array A with as many
 *          instances of array B as the size of array A can handle.
 *  \return The array A
 *  Method:
 *      -#  If /e a = NULL, then the array of size /e sa will be allocated
 *      -#  If /e b = NULL and /e sb = 0, then array will be filled with zeros
 *      -#  If /e sb = 0, the function does nothing and returns NULL
 *      -#  Declares a variable /e i, this is be the pointer offset
 *      -#  Assignes array /e b to array /e a offsetted by /e i, and incriments
 *          /e i by /e sb. This step is repeated until less than sb bytes are
 *          left untreated
 *      -#  Assignes the remaining part of array /e a with whatever piece of 
 *          array /e b fits
 */
VO* afl(register    const   U16 sa, 
        register            VO* a, 
        register            U8  sb, 
        register    const   VO* b   ) {
...
}
albert
  • 8,285
  • 3
  • 19
  • 32
Wispy
  • 141
  • 1
  • 7
  • 2
    Don't shout in your first line!! – albert Apr 03 '21 at 17:23
  • Which version of doxygen / doxywizard are you using? Strange that stack overflow issues an error (what kind of error), but you will have a Doxyfile , by using `doxygen -x` you can reduce its size (it will only give the items different from the default settings). – albert Apr 03 '21 at 17:27
  • @albert, The version of Doxygen 1.9.1. StackOverflow complains that my question mostly consists of code, and you know the Doxygen config is pretty massive. Thanks for advice, I've added the short configuration into the post – Wispy Apr 04 '21 at 11:36
  • Please also add a `*.c` file from which you don't see the functions. Doxygen is sometimes quite strict on when it shows documentation, especially when there is a `*.c` file but not a `*.h` file with the prototypes it doesn't show the functions. Most of the time this can be overcome by adding at the top of the file `/// \file` – albert Apr 04 '21 at 12:39
  • The documentation is missing on any function from any source file, all of the functions have their prototypes in the header file they belong to. Some files have the file documentation in the comments. However, I am using `/**...*...*/` comments, all doxygen keywords start with `\ `, occasionally with `@`. There's really something strange taking place. – Wispy Apr 04 '21 at 16:13
  • The documentation is present above the declaration and above the definition – Wispy Apr 04 '21 at 16:17
  • Please show an example as without an example we don't know why it goes wrong. – albert Apr 04 '21 at 17:56
  • @albert I have posted an example in my answer – Wispy Apr 05 '21 at 18:31

1 Answers1

2

The supplied code gives directly an answer when running it, it gives the warning:

warning: documented symbol 'Array Fill' was not declared or defined.

when looking at the code we see here:

\fn     Array Fill

but from the documentation we learn:

\fn (function declaration)

Indicates that a comment block contains documentation for a function (either global or as a member of a class). This command is only needed if a comment block is not placed in front (or behind) the function declaration or definition.

If your comment block is in front of the function declaration or definition this command can (and to avoid redundancy should) be omitted.

A full function declaration including arguments should be specified after the \fn command on a single line, since the argument ends at the end of the line!

and furthermore in the given example in the documentaion:

  const char *member(char,int) throw(std::out_of_range);

and

/*! \fn const char *Fn_Test::member(char c,int n) 
 *  \brief A member function.
 *  \param c a character.
 *  \param n an integer.
 *  \exception std::out_of_range parameter is out of range.
 *  \return a character pointer.
 */

in other words the syntax for the \fn command should be in this case:

\fn     VO* afl(register const U16 sa, register VO* a, register U8 sb, register const VO* b)

Note:

  1. the \fn command is typically for the usage when the documentation of a function is not directly in font of the function. In the case of the issue the \fn command is not necessary.
  2. It looks like that the \fn here is used in the context of the \brief command and the used \brief command in the context of the \details command.
albert
  • 8,285
  • 3
  • 19
  • 32
  • Thank you! I have completely misinterpreted the use of `\fn` and keywords alike and was completely blind when looking at the output of the Doxygen – Wispy Apr 07 '21 at 18:09