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.
Related
I'm just new to this separating source files.
.
Is it possible to share the my type defined to any other source files?
.
.
.
This is my definitions in myTypeDef.h
typedef struct
{
int x, y, w, h;
short life;
}Man;
What if I create a new .h (named draw.h) file that will draw the image like this:
#include "myTypeDef.h"
void rendererFunction(Man *man);
Then I create a .c (named draw.c) file that will implement what's in draw.h like this:
#include "draw.h"
void rendererFunction(Man *man)
{
draw(man->x, man->y, man->w, man->y);
}
Then what if I also created a update.h (and update.c for implementation) file that will update his position? Do I really have to connect the draw.h to update.h just to get my type defined object? Or is there any other way of sharing type defined object without repeating the definition when I include the .h's in my main??
I hope someone can help me. Thanks
A common idiom in c header files are inclusion guards. These use the preprocessor to prevent things like multiple definitions. They look something like :
#ifndef MYMODULE_MYFILENAME_H
#define MYMODULE_MYFILENAME_H
.... Your definitions....
#endif
This allows you to always include the header containing what a given file is using, even if some other file happens to also include the header you need. Indeed this is good practice so that if later you refactor a header file to no longer include the file you need, some seemingly unrelated code doesn't start failing to compile.
In your update.h, just include "myTypeDef.h". Like what you do with draw.h and draw.c;
Or in your draw.h and update.h, just use sentence struct Man; to declare the struct. And in your draw.c and update.c use include "MyTypeDef.h".
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 1.8.5 and having the same exact problem as in the following question, only the language is C and the enums are in the C files:
Doxygen C# XML comments: multiply enum's with same name and different scope got merged?
According to https://bugzilla.gnome.org/show_bug.cgi?id=522193 it was fixed in 1.6.0, but I'm guessing Doxygen isn't treating different C files as having different namespaces.
The enums in question pertain only to each specific file, but are called the same name because they are used for the same purpose in that file (for flags used to track status information about that module, for example). The C compiler has no problem with this, but Doxygen combines them.
Example:
file1.c
enum status_flags {
sfACTIVE,
sfSHUTDOWN,
sfWARNING,
};
file2.c
enum status_flags {
sfSTANDBY,
sfSCREEN_OWNED,
};
The doxygen file will generate a single blob of both enums combined, including the comments for each member, and reference them in the documentation for both files.
enum status_flags
Enumerator
sfACTIVE
sfSHUTDOWN
sfWARNING
sfSTANDBY
sfSCREEN_OWNED
Definition at line 42 of file file1.c.
and
enum status_flags
Enumerator
sfACTIVE
sfSHUTDOWN
sfWARNING
sfSTANDBY
sfSCREEN_OWNED
Definition at line 65 of file file2.c.
I've tried making each file a member of its own #addtogroup, and I've made sure each file has an #file at the top, but it's still mixing all of these enums together which are supposed to be private to that particular C file. It would be a bit of a pain if I were forced to rename each of these enums, as there are dozens of applications in the code which all follow a similar format and use private enums of the same name with different flags. The compiler is perfectly happy to work with them.
Any ideas?
Anonymous typedef enum also have this same issue,
typedef enum {
sfACTIVE,
sfSHUTDOWN,
sfWARNING
} status_flags;
results in the combining issue, but Doxygen appears
to give priority to the enumeration, so combining
does not happen when you do this:
typedef enum status_flags_f1 {
sfACTIVE,
sfSHUTDOWN,
sfWARNING
} status_flags;
typedef enum status_flags_f2 {
sfSTANDBY,
sfSCREEN_OWNED
} status_flags;
This only works if TYPEDEF_HIDES_STRUCT is set to NO in the Doxyfile configuration file, which is the default.
On a project I'm working I need to know the size of a structure that is defined on a different file.
I tried to use sizeof(name_of_the_structure) but this didn't work because I can't include the other file in the current one.
The header file where the structure is defined has Include Guards and does't allow me to include it on the current file because it has already been included on other file.
I can manually place the size in code, but in the future if a change in the structure is needed I also need to change this.
What can I do in order to discover the structure size?
Thanks in advanced, best regards, Mauro.
If struct ST_ContainerManagement is declared in app_log.h then include app_log.h at the top of SPI25VF064.c and then in it's source do get the structures size.
#include "app_log.h"
...
size_t size_ST_ContainerManagement = sizeof(struct ST_ContainerManagement);
I have #define values in headers that I certainly want Doxygen to document but I have others in C files that I treat as static constants and I don't want Doxygen to document them. Something as simple and stupid as
#define NUMBER_OF(a) (sizeof((a))/sizeof((a)[0]))
#define MSTR(e) #e
How can I keep Doxygen from putting those #defines in the documentation it creates? I've tried marking it with #internal but that didn't seem to help.
A somewhat-related question on Doxygen and #define, how can I get:
#define SOME_CONSTANT 1234 /**< An explanation */
to put "SOME_CONSTANT" and "An explanation" but not "1234" in the output?
There is no need to use the \cond and \endcond commands. You can hide the initializer by simply using the \hideinitializer command:
#define SOME_CONSTANT 1234 /**< An explanation #hideinitializer */
Regarding the first question, you may set HIDE_UNDOC_MEMBERS = YES and only the macros having a Doxygen documentation block will be shown in the output.
You can set MAX_INITIALIZER_LINES = 0 in your doxyfile to hide the values of your defines.
You can exclude any part of code from Doxygen parsing with \cond ... \endcond tags.
edit: Some related questions:
How can Doxygen exclude a C++ class?
Exclude some classes from doxygen documentation
You only want to document what is declared in the .h files. I'm assuming you declare all static functions and variables as static in your .c files. All the remaining are declared in .h corresponding files also. These are your "public" members.
What I like to do in this case, and I believe doxygen was more designed to be used this way is:
in your Doxyfile, set EXTRACT_ALL = NO and add the directory where your .h files are to INPUT
add /** \file */ to all your .h files (but not your .c files).
This will index only what is contained in your .h files. You can still add the directory containing your .c files to INPUT at your Doxyfile, and they will be scanned for additional documentation for your "public" members...
It will no doubt still seem noisy and unnatural, but to address your other question, try:
/** An explanation */
#define SOME_CONSTANT /** #cond */ 1234 /** #endcond */
I solved this problem by moving my documentation from the .c file to the .h file. Then run doxygen only on the .h file.
Then the items that I want to document (the 'public' items) are intrinsically what doxygen picks up.
Because I have been previously careful to put 'public' items in the .h file and 'private' items in the .c file this works very well.
This technique came to mind when I noticed that doxygen was pulling in the includes. It struck me that if I were to also move the subset of includes that the calling module would need to use my module, then that list would be documented as well.
This technique has an additional benefit: I can put the documentation in one terminal window and the source in a different terminal window while updating the documentation.
Sometimes you may have a define which you want to document, but want doxygen to treat it differently (or even ignore it completely to avoid parsing errors).
For this you can define the #define in doxygen differently than in your sourcecode.
Example:
Some compilers allow variable linkage to specific segments, i.e.:
const int myvar # "segment_of_myvar_in_memory"=123;
=> doxygen would parse the "segment_of_myvar_in_memory" part as variable name which is not desired.
We could use a define for it:
#define __link_to_segment(name) # name
const int myvar __link_to_segment("segment_of_myvar_in_memory")=123;
If Preprocessing is active, Doxygen interprets our variable now as a function because of the function-like define using brackets..
But if we redefine our define within the Doxyfile, behaviour changes:
PREDEFINED = __link_to_segment(a)=
now the variable is parsed correctly as variable - also all types or keywords in front are correctly shown as keywords.
A nice side effekt:
In case you use 2 different IDEs with your code (one IDE for compiling&debugging, one for editing), you will also discover that some IDEs (i.e. Eclipse) have problems parsing variables with #"segment name". Using the approach above, you can redefine the __link_to_segment(name) there too:
#define __link_to_segment(name)
i.e. Eclipse will then show and parse the variable correctly, whereas the "compiling&debugging" IDE can still link the variable to its segment name.