Is it possible in Doxygen to add a brief description of a struct declared but not defined? For example, running doxygen <config file> (where <config file> is the configuration file with default parameters) in the folder with the file mydefinition.h
#ifndef MYDEFINITION_H_
#define MYDEFINITION_H_
/** My super secret structure you can't access fields */
struct MyStructure;
/** The function that lets you use any instance of 'struct MyStructure'
* #param msobj the object
*/
void functionUsingMyStructure(struct MyStructure* msobj);
will generate the documentation of the functon but not the documentation of the structure.
I tried to modify the configuration file of Doxygen by setting OPTIMIZE_OUTPUT_FOR_C = YES but it doesn't change the situation.
Doxygen ignores forward declarations of structs. To workaround this, you have to explicitly state that the given comment block describes your struct.
/** #struct MyStructure
* My super secret structure you can't access fields
*/
struct MyStructure;
Related
I've got the problem that doxygen will auto document all typedef structs from header files which are included in the configurations. They are listed as "Data structures" in the HTML documentation on the sidebar. Which option is needed to deactivate the auto documentation from structs? Thanks!
Since your struct definiton goes in the header file doxygen will document it automatically unless you define your structure in related C file; in this case it'd be private and could be prevented to output by setting the following options to NO:
EXTRACT_ALL
EXTRACT_PRIVATE
EXTRACT_STATIC
But since the definition resides in your header file you can hide it either by setting the EXCLUDE_SYMBOLS to your struct symbol/definiton name(s) or as an alternative to the EXCLUDE_SYMBOLS option you can use hideinitializer command in the comment section of your struct type in the source code.
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.
We do have several C-projects targeting resource-constrained systems, which rely heavily on enums defined through preprocessor macros in special resource files. These files get included within the enum definition.
This concept is used to have the user of our API to "be only allowed" to edit the resource definition file, but not needing to touch the header file where these enums are actually defined. Additionally it allows to generate strings for these events, too.
Example for a resource file
DEF_SOME_EVENT_TYPE(EVENT_ALERT)
DEF_OTHER_EVENT_TYPE(EVENT_OTHER_ALERT)
DEF_SOME_EVENT_TYPE(EVENT_FLASH)
DEF_SOME_EVENT_TYPE(EVENT_BEEP)
Example for the associated enum definition
enum some_event_e
{
#define DEF_SOME_EVENT_TYPE(name) name,
#define DEF_SOME_OTHER_EVENT_TYPE(name)
#include "resource_definitions.g"
#undef DEF_SOME_EVENT_TYPE
#undef DEF_SOME_OTHER_EVENT_TYPE
SOME_EVENT_COUNT
};
enum some_other_event_e
{
#define DEF_SOME_EVENT_TYPE(name) name,
#define DEF_SOME_OTHER_EVENT_TYPE(name)
#include "resource_definitions.g"
#undef DEF_SOME_EVENT_TYPE
#undef DEF_SOME_OTHER_EVENT_TYPE
SOME_OTHER_EVENT_COUNT
};
When trying to document the enumerators, doxygen seems to not properly expand these macros and include the resource definition file.
Suppose we have the following documentation block:
/*!
#enum some_event_e
#brief Some event identifiers
*/
/*!
#var some_event_e::EVENT_ALERT
#brief alert event
*/
/*!
#var some_event_e::SOME_EVENT_COUNT
#brief Total number of some events
*/
Doxygen will properly document SOME_EVENT_COUNT, but will throw a warnign for EVENT_ALERT.
warning: documented symbol 'some_event_e::EVENT_ALERT' was not declared or defined.
ENABLE_PREPROCESSING and MACRO_EXPANSION are both set to YES in Doxyfile and I've added *.g (the file-extension used for resource definitions) to the INCLUDE_FILE_PATTERNS and did add it to EXTENSION_MAPPING via g=C. I'm using doxygen version 1.8.16.
Is there a way to be able to document enum values declared in this manner? In some cases it is really useful to use this sort of macro-magic to define enums, so it would be immensely helpful if it was possible to document these with doxygen.
I'm creating a module in C. When I refer to that module in the documentation, I want a link to the header file, not the struct (because the functions and other useful information are at the file level).
The file my_iterator.h contains
typedef struct {
int foo;
int bar;
} my_iterator_t;
I would like references to my_iterator to create a link to my_iterator.h. For example,
/**
Create a new, specially configured my_iterator
*/
my_iterator_t* special_factory_in_another_module();
Putting "my_iterator.h" in the documentation would create the correct link, but would sound strange. Putting my_iterator_t in the documentation would sound better, but not link to a useful place.
Although it is a bit verbose, this does what I want:
/**
* Create a new, specially configured [my_iterator](#ref my_iterator.h)
*/
my_iterator_t* special_factory_in_another_module();
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?