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?
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
This issue is due to doxygen parsing constraints. I am using doxygen 1.8.11 with Eclox (the eclipse plugin) in Kinetis Design Studio for embedded C development.
Almost all of the doxygen compiling works, except I need to have a few very large static arrays. I didn't want to clutter up the main code, so I used a hack I found on these forums (https://stackoverflow.com/a/4645515/6776259):
static const float Large_Array[2000] = {
#include "Comma_Delimited_Text_File.txt"
};
Unfortunately, that hack is causing the compile of my main.c main_module group to fail. With the following error:
warning: end of file while inside a group
I've tried excluding those constants from my main_module group with something like the following:
/*!
** #addtogroup main_module
** #{
*/
...
... header code ...
...
/*!
** #}
*/
static const float Large_Array[2000] = {
#include "Comma_Delimited_Text_File.txt"
};
/*!
** #addtogroup main_module
** #{
*/
...
More code, definitions, etc.
None of this is generated in the doxygen compile...?
/*!
** #}
*/
This gets rid of the doxygen compiling error, but the compiled doxygen documentation does not include anything after the Large_Array declaration. So it seems the second #addtogroup statement is not working.
Am I missing something simple? Any help is appreciated. Thank you.
If Comma_Delimited_Text_File.txt doesn't have trailing linebreak, then try adding one.
Doxygen gets confused if include file doesn't end with linebreak. This can break the document generation for other files too, even when they don't seem related. Often this results in missing symbols and broken callgraphs.
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 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'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?