doxygen:dox - chunhualiao/public-docs GitHub Wiki

Lesson

qualified name of SageInterface::get_name() , we need both .h and .cxx file for Doxygen to correctly parse it!!
namespace SageInterface { isScalar().. }, only .cxx file is sufficient!


/**
 * @fn long long calculateFactorial(int n)
 *
 * @brief Calculates the factorial of a non-negative integer.
 *
 * This function computes the factorial of a given non-negative integer using
 * a recursive algorithm. The factorial of a number n is defined as the product
 * of all positive integers less than or equal to n.
 *
 * @param n The non-negative integer for which the factorial is to be calculated.
 *          Must be greater than or equal to 0. If n is greater than 20, the result
 *          may overflow a 64-bit integer.
 *
 * @return The factorial of the input integer n. Returns 1 if n is 0, as 0! is defined as 1.
 *
 * @warning Large values of n (n > 20) can cause an overflow in the return value,
 *          since the result may exceed what a 64-bit long long can hold.
 *
 * @pre The input integer n must be non-negative (>= 0).
 *
 * @post The function returns the factorial of n, which is always positive or zero.
 *
 * @note This function uses recursion and might cause stack overflows for large values of n,
 *       although this is unlikely to occur in practice due to the overflow issue mentioned above.
 *
 * @example This example demonstrates how to use this function:
 *          @code
 *              int num = 5;
 *              long long result = calculateFactorial(num);
 *              std::cout << "The factorial of " << num << " is: " << result << std::endl;
 *          @endcode
 */

for doxygen, i already have functions within .cpp files. Can I docoument these functions in a separated dox files? How to do so that Doxygen can correctly connect dox file content to the functions within .cpp files?

Yes, you can keep the Doxygen comments for your functions in separate .dox (or similarly named) files rather than inline in the .cpp or header files. The key is that Doxygen must be able to “match up” those comments to your actual function definitions or declarations. Below is a step-by-step approach.

1. Make sure Doxygen processes your `.dox` files

In your Doxygen configuration file (Doxyfile), ensure that:
- FILE_PATTERNS includes *.dox (or whatever extension you use for your documentation files). For example:
```
FILE_PATTERNS = *.h *.hpp *.cpp *.dox
```
- INPUT includes the directory(ies) where you keep those .dox files.
If you have not changed the defaults, also confirm that:
```
RECURSIVE = YES
```
(or set it to YES if your docs and source code are in different subdirectories and you want Doxygen to crawl them).

This ensures that Doxygen actually sees your .dox files and parses them.

2. Use the `\fn` command (or equivalent) with the correct signature

In your .dox file, you can document a free function or a member function with a documentation block containing the \fn command (or by using the /*! */ style block with a \fn tag inside it). For example:

/*! 
  \fn int myFunction(int a, int b)
  \brief Does something with integers.

  Detailed description of what myFunction does, usage details, etc.

  \param a the first integer
  \param b the second integer
  \return some computed result
*/

The function signature in the \fn line must match exactly the signature of the function definition found in your .cpp file.

If this function is in a namespace or class, you must include the fully qualified name. For example:

/*!
  \fn double MyNamespace::MyClass::myMethod(int x, int y)
  \brief Explanation of myMethod.
  ...
*/

And in your .cpp, you might have:

double MyNamespace::MyClass::myMethod(int x, int y)
{
    ...
}

By doing this, Doxygen will link that documentation comment to the corresponding function in the compiled documentation.

3. Alternatively, use the `\file` or grouping approach

Another approach is to create a block in your .dox file that “belongs” to a file or module, and within that block, reference your functions. For example:

/*!
  \file myModuleDocs.dox
  \brief Documentation for the functions in `myModule.cpp`.

  Here is some high-level documentation about `myModule.cpp`.
*/

/*!
  \fn int myModuleFunction(int a, int b)
  \brief Detailed documentation for myModuleFunction.

  \param a ...
  \param b ...
*/

If the function is a member of a class or namespace, remember to fully qualify it.

4. Verify by running Doxygen and checking output

After setting this up:

Run doxygen Doxyfile.
Look in your generated documentation (HTML, for instance) to see if your function is listed and properly documented.
If the function still appears “undocumented,” check that the signature matches exactly (including any namespace or class scope).

5. Common pitfalls

Signature mismatch:
Doxygen will fail to link the comment to your function if the signature differs in any way (return type, parameter types, namespaces, or class scopes).
Not including .dox in FILE_PATTERNS:
If .dox is not included, Doxygen won’t parse the file at all.
Forgetting fully qualified names for class/namespace methods:
If you do not provide the namespace or class scope for non-free functions, Doxygen won’t match them up.
Member function vs free function:
If your function is a member function but you document it like a free function (or vice versa), Doxygen will not link them.

Example

Let’s say you have example.cpp:

#include "example.hpp"

namespace MyNS {

int exampleFunction(int a, int b)
{
    return a + b;
}

}

And you want to document MyNS::exampleFunction in example_docs.dox, separately:

/*!
  \fn int MyNS::exampleFunction(int a, int b)
  \brief Adds two integers together.

  This function simply returns the sum of the two input integers.

  \param a First integer
  \param b Second integer
  \return The sum of \a a and \a b
*/

Make sure your Doxyfile includes:

INPUT = . 
FILE_PATTERNS = *.cpp *.hpp *.h *.dox
RECURSIVE = YES

Run Doxygen:
```
doxygen Doxyfile
```
Check the generated documentation—MyNS::exampleFunction should now appear with the documentation block you provided in example_docs.dox.

Conclusion

Documenting your .cpp functions in a separate .dox file is perfectly valid as long as:

The .dox files are included in Doxygen’s input paths and patterns.
The \fn or related command exactly matches the function signature in the source code.
(Optional) You include the namespace/class scope in the documentation if needed.

With these steps followed, Doxygen will correctly “connect” the separate documentation to the actual function implementation.