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
Related
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
Iknow there similar questions to this,but I didn't find an answer that can solve my problem, I have Program composed of one Header file, that includes mutiple static variables and functions.
the variable are used in mutiple source file, and have then different meaning , the functions too are implementet in different way in each time . My question is how can my comment in the source file be sees in HTML doxygen file. like :
/*!<
function that does stuff
#param value representing the mean stuff
*/
double func(double* value){
FILE* inp =NULL; /*!< the file pointer of this function to write the result*/
.............................................//!* all this commments should be see in functiopn description
}
and by the I know that , if I open the source file in the documentation I'll see the comment , but I want to explain the roll of each function and how it doing its job!
thanks in advance for any help!
Here it is http://www.doxygen.nl/manual/docblocks.html#specialblock
If you just comment with // it won't appear on doxygen. Doxygen only parses comments starting with certain tokens, such as /** or /*!
I have some includes in the source code where I want to add some "to do".
For example:
/** \todo Review. */
#include "anyfile.h"
/** todo Another to do. */
#define ANY_MACRO 1
The problem is that the first "to do" is inserted in the macro definition and not in the include, as followed:
-----------------------------------
**Todo List**
Global **ANY_MACRO**
Review.
Another to do.
-----------------------------------
Any idea how to solve this ?
Following the online doc:
Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined.
Then I handle your problem in the following manner: I must have a \file comment in both files, and above the include line, I mention that the todo part refers to the included file.
In other words, I write this in my source file afile.c:
/** \file anyfile.h
* \todo Review
*/
#include "anyfile.h"
/** \file afile.c
* \brief Some code
*/
/** \todo wait, a todo !*/
#define A_MACRO
int main()
{}
In the included file, I write a short comment about the file itself:
/** \file anyfile.h
* Very interesting header
*/
#define B_MACRO
As output, the todo comment is placed in the doc page of the included file. The awkward part according to me is that I have to put the block /** \file afile.c */ after the include line, otherwise it doesn't work.
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.