I'm using a 3rd party API C sources where special documentation blocks are as following
/****************************************************************************************
* #fn fn
*
* #brief brief
*
* #param param
*
* #return return
****************************************************************************************
*/
void fn(void)
{
...
}
Is there a way to convince Doxygen these are real special documentation blocks without modifying sources in order to match standard block (e.g. exactly two asterisks at block start)?
Thank you in advance.
I suggest to create an input filter that replaces /****** by /** and add that to the INPUT_FILTER
option in the configuration file. If you have the Unix command sed on your system, the following would do the trick:
INPUT_FILTER = "sed -e 's|/\*\*\**|/**|g'"
Related
I have noticed, that when using Doxygen to document a .c file, the list of includes in the given file is also included in the output, for instance:
https://agnix.sourceforge.net/documentation/api/bridge_8c.html
Now, what I typically do, is include some general comments before a given "include block" ("intro comments"), and then some specific comments on the same line as the include line:
...
/*
* The following includes are required for
* the code to compile:
*/
#include <stdio.h> // contains printf()
#include <netinet/in.h> // contains sockaddr_in
...
Is it possible to have these kinds of comments formatted for Doxygen, (either "intro comments", or "on same line" - hopefully both), such that I get them output in the final documentation for that .C file?
Essentially, for the above example, I'd get an output like this (screenshot is from manually hacked HTML, to get a mock-up of desired output):
(I guess, this could be seen as a somewhat of a "literal programming" approach)
If you want Doxygen recognizes a file to insert it in documentation, you should use
/** <- (this format is recognized by Doxygen)
* #file name_of_file.h
*
* #brief What is
*
* #author You
*
* #date 03/01/2023
*
* #par Put the title of the paragraph
* Write the content of the paragraph
*/
at the beginning of your header file (note: #file is mandatory).
Read also Doxygen guide
When I select ColumnLimit any non-zero value. It converts block comments into Doxygen block comments (it adds space before * on a new line). But I do not want to change it. How can I disable it?
My .clang-format file
ColumnLimit: 100
IndentWidth: 4
TabWidth: 4
UseTab: Never
It converts the following block comments
/*****************************************************************************
* A brief comments.
*
* #param theory .
*
******************************************************************************/
into this
/*****************************************************************************
* A brief comments.
*
* #param theory .
*
******************************************************************************/
NOTE: It added spaces before each line, I do not want these spaces.
And I don't want to solve this by disabling clang-format for every Doxygen comment block. That seems ridiculous.
Any good suggestions? :-)
Add the following line in your .clang-format file
CommentPragmas: '^[^ ]'
This will force the clang-format not to alter any comments in the code.
I am currently documenting some advanced simulation tools using Doxygen. I would like to be able to refer to equations within the HTML documentation.
To illustrate the problem. Perform the following
doxygen -g Doxyfile
sed -i 's/^EXTRA_PACKAGES.*/EXTRA_PACKAGES = amsmath amsfonts/g' Doxyfile
sed -i 's/^LATEX_BATCHMODE.*/LATEX_BATCHMODE = YES/g' Doxyfile
You now have a Doxyfile, which can be used for a project containing formulas.
In the same directory put the following
sample.h:
/**
* #file sample.h
*/
/**
* #mainpage Some example
*
* Some complicated math:
* \f{equation}{\label{eq:1}
* p(\vec{r}_{0},t) = \ldots
* \f}
*/
/**
* The function computes the pressure based on \f$\ref{eq:1}\f$
*
* #param rho
* #param v
* #param r
* #param t
*
* #return
*/
int CalcPressure(float rho, float v[3], float r[3], float t);
Execute the following to generate LaTeX documentation.
doxygen Doxyfile
cd latex
make
A reference to equation (1.1) is put in the documentation for the CalcPressure function.
The HTML documentation on the other hand contains a '??' reference to the formula. Is it possible to tweak doxygen to run twice for the generation of formulas, such that the image created contains the reference '(1.1)' rather than '??'.
Another solution may also work. I know how to include references to functions in another LaTeX document by using the xr package, http://www.cheshirekow.com/wordpress/?p=335
I could use this procedure, if I could tell Doxygen to not delete the _formulas.aux file, rename the file and pass this as input using the xr package, but I have no idea of how to tell Doxygen not to delete temporary files.
I hope there is a solution for creating references to formulas. Help please
A partial answer. To remove the ?? from html, make the link only in latex
/**
* The function computes the pressure based on #latexonly\ref{eq:1}#endlatexonly
*/
But this way you won't get a link in html.
I managed to find a solution myself.
I created a script
Linux: latex2
#!/bin/bash
if [ $# -lt 1]; then
echo $0: usage: latex2 args
exit 1
fi
latex $*
latex $*
Windows: latex2.bat
#echo off
call latex %*
call latex %*
and changed the LATEX_CMD_NAME in Doxyfile to execute this script or actually use a definition set by CMake
Doxyfile.in
LATEX_CMD_NAME = #LATEX_CMD_NAME#
CMakeLists.txt
if (UNIX OR CYGWIN)
set( LATEX_CMD_NAME "${PROJECT_SOURCE_DIR}/bin/latex2")
else()
set( LATEX_CMD_NAME "${PROJECT_SOURCE_DIR}/bin/latex2.bat")
endif()
As the title suggests, I want to enforce source code documentation for a C project managed in Subversion.
My idea is: set up a pre-commit hook that use doxygen for checking files with this options
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = YES
The problem is: in order to have doxygen take into account a source file and raise warnings for undocumented members, It seems I must put into that file the "\file" documentation block as you see below.
/** \file foo.h
* A file for testing how to enforce documentation
*
* if I don't put voluntarily this first "file" block,
* doxygen "ignores" the file and does not generate the warnings
* I would expect (note that otherfunction is not documented)
*/
#ifndef FOO_H_
#define FOO_H_
/**
* \brief my test function
* \param msg a simple string
* \return 0 if ok, 1 if not ok
*/
int testFunction(const char *msg);
int otherFunction(const char *msg);
#endif
If I don't doxygen "ignores" the file and no warning is raised.
This makes the check uneffective: users can easily forget to put the required block at the beginning of the source and commit without control.
Is there a way to make doxygen enforce the /file block in the beginning of the file?
I've got the following problem using Doxygen 1.7.x: I document various files in a subdirectory and they are referred with different filename styles, both with and without their path, on the corresponding Modules page. But I want to have relative paths (w.r.t. the project root) on the modules page.
The two files are tagged as follows:
/**
* #addtogroup examples_itsolver
* #{
* #file example/itsolver/bicgstab_1.c
* #brief Demostrate the usage of BiCGStab
* #date 05/21/2012
* #version $Id$
*#}
*/
and
/**
* #addtogroup examples_itsolver
* #{
* #file example/itsolver/sor.c
* #brief Demostrate the usage of SOR
* #date 05/21/2012
* #version $Id$
*#}
*/
This results in
file bicgstab_1.c
Demonsrate the usage of BiCGStab.
file example/itsolver/sor.c
Demonstrate the usage of the SOR Iterative Solver.
on the Module overview page. But I want to have all files documented like sor.c across the whole project. How can I achieve this? Using the FULL_PATH_NAMES configuration option does not help.
A full example (including the generated html output) is available on http://www-e.uni-magdeburg.de/makoehle/doxygen_error.tgz
The problem is that in your example there are two files called sor.c
example/itsolver/sor.c
lib/itsolver/sor.c
doxygen will prepend as much of the path as needed to make the name unique.
If example contains usage examples, then it is better not to include these in the input, but use #snippet, #include, or #example instead and point EXAMPLE_PATH to your example directory.