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.
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
Doxygen is able to document structs but it's not exporting any function declarations or macro definitions.
For instance these defined in headers are not exported.
/** Total instances */
#define TOTAL 10
/** Initializer */
void InitProduct(Product *product, const char *productName);
I'm using Doxygen GUI on Windows, appreciate a GUI reference.
Doxygen is fussy about what documentation it extracts when not EXTRACT_ALL.
Structures and classes are generally okay; functions and variables not so.
To get documentation extracted for functions and variables at the file-level scope, there needs to be a #file documentation element in that file:
/** #file frobulator.c
* Optionally describe the file...
*/
/** #brief My Frobulator.
*/
void frobulator () { ... }
This is for both headers and source files.
For functions and variables at namespace scope, the namespace also needs to be documented with #namespace or in situ. Unlike other elements, namespaces have no "single" point of declaration where documentation can be placed. I usually end up creating a separate .dox file to contain #namespace docs in C comment blocks.
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'm trying to use Doxygen, but I can't make it work with my code. In a nutshell, if it contains #include's Doxygen just ignores it. This is a MWE:
/*!
\file
\brief This foos bars
\author John doe
*/
#include <stdio.h>
#include <stdlib.h>
/*!
\brief print a net.
This prints nets.
\param net Net to print.
*/
void printf_net(int8_t* net){
printf("%d\n",L);
for(int i=0;i<L*L*L;i++){
printf("%d\n",net[i]);
}
}
If I comment the #include's, documentation is generated for the function, but not with them. What should I correct in my code?
Updates:
In response to the comments,
Using /** instead of /*! doesn't seem to change the behaivour.
I have ENABLE_PREPROCESSING = YES in my Doxyfile. Basically, I have all the default values of the graphical wizard.
I'm using Doxygen 1.8.12
UPDATE:
I was enabling HAVE_DOT by accident. Disabling that option fixes my problem.
I'm using doxygen to comment a pure C project. The documentation for a struct is of the following form:
/** #struct cl_options
* #brief This structure contains all ...
* #var cl_options::input_file
* Member 'input_file' contains ...
* #var cl_options::output_file
* Member 'output_file' contains ...
* #var cl_options::bitrate_mode
* ...
*/
struct cl_options {
FILE* input_file;
FILE* output_file;
....
};
Nevertheless I get warnings:
.../commandline.c:39: Warning: Member input_file (variable) of class cl_options is not documented.
.../commandline.c:40: Warning: Member output_file (variable) of class cl_options is not documented.
and so on. For all the structures within the project.
There is a decleration in the header file commandline.h
struct cl_options;
typedef struct cl_options cl_options;
but the doxygen is in the .c-File.
Now the generated doxygen has a link for the struct in the data structures section but it is not documented. Instead there is a link which says
The documentation for this struct was generated from the following
file: commandline.c
and then there is the documentation I provided in the .c-file. How can I avoid this?
I noticed a lot of warnings myself, while using doxygen, however most of the time the output seemed to be fine with me. You can turn, different warnings on and off. For more information visit the doxygen manual and choose which warnings your want to be enable.
However, you can try to move your #var tags from your .c file to your .h header. Just leave the documentation of functionality from your struct, in your .c.
Also, you might want to take a look at this post, with a similar question.
using-doxygen-with-c-do-you-comment-the-function-prototype-or-the-definition? Or both?