I'm using doxygen to document some C code. I have doxygen friendly comments:
/**
* some comment
*
* #param a something
*/
and my directory structure looks like this:
libproject/
src/
project.h
project.c
docs/
project.doc.conf
index.txt
Makefile
I have generated project.doc.conf with doxygen -g project.doc.conf and configured the INPUT tag to be
INPUT = index.txt ../src/
I've also added a dummy index.txt:
/*! \mainpage My Personal Index Page
*
* \section intro_sec Introduction
*
* This is the introduction.
*
* \section install_sec Installation
*
* \subsection step1 Step 1: Opening the box
*
* etc...
*/
for testing. When I run:
$ doxygen project.doc.conf
I get two new folders in libproject/docs/: html and latex. So far, so good.
However when I navigate to index.html in my browser I just get the index page and a list of files. I can browse the source but the documentation is missing!
Where is the documentation? Do I have to specify some tags for doxygen to draw it?
You must document each file using:
/**
* #file project.h
* #brief some brief description
*/
http://www.doxygen.nl/manual/docblocks.html#structuralcommands
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
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?
The header comments in my main.c are not being processed by doxygen, however if I rename the file from main.c to for example mainn.c it works very well.
Why is main.c treated differently from an other file name?
How do I make Doxygen manage main.c as other .c files?
Or alternatively, what is the best practice here? My purpose in Main.c is to put a short (maybe not so short) product description and use cases in the header documentation.
The header file starts as such:
/**********************************************************//**
* #file main.c
* #author Somebody
* #brief Main function and support functions.
* #details
Then continues with application level things I want to document.
Doxygen configuration is the default as it is installed, except for a few items, such as optimised for C, include call charts etc...
Thanks..
Kinda hard to tell without seeing how you've tried to document it... But make sure you have a line in the main.c file that reads
/*! file */
or
/** #file */
(Doxygen doesn't document global objects by default)
After mucking around a bit here is the solution. (As proposed by MPI_What.
As mentioned in my question
/**********************************************************//**
* #file main.c
* #author Somebody
* #brief Main function and support functions.
* #details
Works for all files except main.c (Of course the line #file main.c is different for the other files. However the following works well for main.c also:
/**********************************************************//**
* #file
* #author Somebody
* #brief Main function and support functions.
* #details
Why it works is a mystery, but it does.
Thanks, Adrian
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.