I want to generate documentation only for code that has Doxygen comments. I have created a Doxyfile via Doxygen version 1.8.9.1 and configured it to output only XML and to hide all undocumented code:
GENERATE_HTML = NO
GENERATE_LATEX = NO
GENERATE_XML = YES
HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES
After that I created a simple C header test.h with one documented and one non-documented function declaration:
void foo(int a);
/**
* "bar" function description
* #param b sample param
*/
void bar(int b);
By executing doxygen I expected only documentation for bar to be included in the resulting XML. Unfortunately, documentation for both functions is generated. Is it possible to generate documentation only for code that has Doxygen comments? Or will Doxygen always include everything in the XML output regardless of settings?
Before reading any further make sure EXTRACT_ALL is set to NO.
I'm not a fan of the following solution but it does work. Use doxygen's preprocessor
#ifdef PROJECT_NO_DOC
void foo(int a);
#endif /* PROJECT_NO_DOC */
/**
* * "bar" function description
* * #param b sample param
* */
void bar(int b);
Note, in their docs you have to set a PREDEFINED macro but at least in my version of doxygen this was not required. Their docs specify to do it this way set a predefined macro in the config to do it for you
#ifndef DOXYGEN_SHOULD_SKIP_THIS
/* code that must be skipped by Doxygen */
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
around the blocks that should be hidden and put:
PREDEFINED = DOXYGEN_SHOULD_SKIP_THIS
in the config file then all blocks should be skipped by doxygen as long as
ENABLE_PREPROCESSING = YES
There are other methods but they come with additional constraints ie to make sure no static method appear in your public docs you can set EXTRACT_STATIC to NO.
You can use \cond to hide parts of the source code from Doxygen. This avoids the need to use the preprocessor as in Harry's answer.
For example, here foo will not be seen by Doxygen, and hence not documented:
/** \cond */
void foo(int a);
/** \endcond */
/**
* "bar" function description
* #param b sample param
*/
void bar(int b);
Furthermore, it is possible to add section labels to \cond, and control which sections are included by listing them in the ENABLED_SECTIONS configuration option.
For example:
/// \cond CLASS_A
/// This function foos `a`.
void foo(int a);
/// \endcond
/// \cond CLASS_B
/// This function bars `b`.
void bar(int b);
/// \endcond
By setting ENABLED_SECTIONS = CLASS_A CLASS_B, both functions will show up in the documentation. Leaving one of the labels out will hide the corresponding function.
Related
I have rather big project with doxygen and some files marked as #internal, some not.
When I build internal documentation no warnings are generated, but when I try to build not internal I got some warnings:
some_header.h:61 warning: explicit link request to 'MyStruct' could not be resolved
some_header.h:58 warning: explicit link request to 'AnotherMyStruct' could not be resolved
some_header.h:58 warning: explicit link request to 'AnotherMyStruct' could not be resolved
some_header.h:61 warning: explicit link request to 'MyStruct' could not be resolved
But some_header.h is internal. As an idea I think that it is included in non internal file, but it is wrong. I deleted all includes of the header, but the message doesn't gone.
How can I fix this warning?
P.S. duplicates of warning mean that there 2 places with error?
$doxygen -x
FULL_PATH_NAMES = NO
JAVADOC_AUTOBRIEF = YES
OPTIMIZE_OUTPUT_FOR_C = YES
EXTRACT_STATIC = YES
QUIET = YES
WARN_IF_UNDOCUMENTED = NO
WARN_FORMAT =
FILE_PATTERNS = *.c *.h
RECURSIVE = YES
EXAMPLE_PATTERNS =
SOURCE_BROWSER = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
ALPHABETICAL_INDEX = NO
HTML_OUTPUT =
SEARCHENGINE = NO
GENERATE_LATEX = NO
LATEX_OUTPUT =
PDF_HYPERLINKS = NO
USE_PDFLATEX = NO
RTF_OUTPUT =
MAN_LINKS = YES
MACRO_EXPANSION = YES
EXPAND_ONLY_PREDEF = YES
PREDEFINED = (a lot of)
TEMPLATE_RELATIONS = YES
Simple example to reproduce problem:
flags.h:
/**
* #file
* #brief Public Flags.
*/
#ifndef PUBLIC_FLAGS_H
#define PUBLIC_FLAGS_H
#pragma once
/**
* Public flags
*/
typedef enum {
FLAG_READ = 1, /**< reading allowed */
FLAG_WRITE = 2, /**< writing allowed */
} PublicFlags;
#endif /* PUBLIC_FLAGS_H */
info.h
/**
* #file
* #brief Public header.
*/
#ifndef TEST_PUBLIC_H
#define TEST_PUBLIC_H
#pragma once
#include "flags.h"
/**
* Defines public enum.
*/
typedef enum EPublicEnum {
TestEnum1, /**< enum 1 */
TestEnum2, /**< enum 2 */
TestEnum3 /**< enum 3 */
} PublicEnum;
/**
* Defines public struct.
*/
typedef struct SPublicStruct {
PublicEnum state; /**< state (see #PublicEnum). */
unsigned flags; /**< set of flags see #PublicFlags.*/
} PublicStruct;
#endif /* TEST_PUBLIC_H */
internal_enums.h
/**
* #internal
* #file
* #brief Internal Enums
*/
#ifndef INTERNAL_ENUMS_H
#define INTERNAL_ENUMS_H
#pragma once
#include "flags.h"
#include "info.h"
/**
* Possible types:
*
* TypeMisc - Misc type.
* TypeIo - IO type.
*/
typedef enum {
TypeMisc,
TypeIo,
} InternalEnumType;
/** Owner type. */
typedef enum {
Kernel = 0, /**< kernel. */
User = 1 /**< user. */
} InternalEnumOwner;
#endif /* INTERNAL_ENUMS_H */
internal_struct.h
/**
* #internal
* #file
* #brief Internal structures.
*/
#ifndef INTERNAL_STRUCT_H
#define INTERNAL_STRUCT_H
#include "internal_enums.h"
typedef struct SInternalStruct {
rtl_uint8_t owner : 1; /**< values from #InternalEnumOwner */
rtl_uint8_t type : 1; /**< values from #InternalEnumType */
} InternalStruct;
#endif /* INTERNAL_STRUCT_H */
problem:
warning: explicit link request to 'InternalEnumOwner' could not be resolved
warning: explicit link request to 'InternalEnumType' could not be resolved
There is a misunderstanding about what the \internal command does in doxygen does, from the documentation:
24.29 \internal
This command starts a documentation fragment that is meant for internal use only. The fragment naturally ends
at the end of the comment block. You can also force the internal section to end earlier by using the \endinternal
command.
If the \internal command is put inside a section (see for example \section) all subsections after the command
are considered to be internal as well. Only a new section at the same level will end the fragment that is considered
internal.
You can use INTERNAL_DOCS in the configuration file to show (YES) or hide (NO) the internal documentation.
This means that the comment between the \internal and the \endinternal (or end of the comment block) is not part of the documentation (unless the setting INTERNAL_DOCS is set), in this case it is just about the parts like:
/**
* #internal
* #file
* #brief Internal structures.
*/
so the \internal command here has not the desired effect and should be removed.
What actually is desired (when I understand it correctly) is that the entire file isn't used. This can be accomplished by means of either:
add the setting EXCLUDE_PATTERNS = internal*
or
explicitly listing all files and directories that should be used, her this is by adding the setting INPUT = info.h flags.h
In case only part of a file, i.e documentation and code, should not enter the documentation one can use the commands \cond ... \endcond. For disabling just part of a documentation block the commands \if .. \endif are useful. Both sets of commands go together with the setting ENABLED_SECTIONS.
For a description of the mentioned command see the doxygen manual (e.g. at https://www.doxygen.nl/manual/index.html and more specifically the chapters: https://www.doxygen.nl/manual/config.html and https://www.doxygen.nl/manual/commands.html)
I have some code like the following example:
/** #file HelloPi.c */
/** The definition of pi */
#define PI 3.1415
/** #brief The main function.
* #details Prints the value of #PI, which is actual defined as 3.1415. */
void main()
{
printf("The value of pi is %f\n",PI);
}
In my doxygen dokumentation I would like to to have NO macro expansion for PI (and other defines) in general.
But on one paragraph in the documentation I need the value of pi (e.g. #details description of the main function).
Is there any possibility to expand the macro at this single part of documentation with a command or something? Something like /** #details ...the value of #PI is $(PI).*/
I only know the build-in MACRO_EXPANSION tag which works for the whole documentation: https://www.doxygen.nl/manual/preprocessing.html :-/
Thanks for help :)
Jan
Edit:
Add an other example which maybe better describes my Problem:
/** #file ErrorHandling.c */
#define ERR_CODE_POWERUNIT 1001 ///< Error in power unit */
/** #page errors
* [value of ERR_CODE_POWERUNIT ] means \copybrief ERR_CODE_POWERUNIT */
void errHandler(int error)
{
if(error=ERR_CODE_POWERUNIT)
printf("Error %d occur\n",ERR_CODE_POWERUNIT);
}
In the documentation I would like to have:
"1001 means Error in power unit"
In doxygen there is no possibility to do a conversion of a predefined variable (only) in the documentation.
You used in your documentation the an environment variable $(PI) but ths is quite cumbersome as you have to st the environment variable each time.
A better solution would be to use an ALIASES like:
ALIASES += pi=3.1415
or
ALIASES +\= "The value of PI = 3.14159265359..."
with which you define a command \pi that can be used in the documentation and will be replaced with the text / commands in the alias.
/** #details ...the value of #PI is \pi.*/
would result in something like (by head:
...the value of #PI is 3.1415
Want to generate html-documenation from a documented c-header. But I have a strange problem with doxygen:
Some entries (enums, structs, ..) are missed in the html. If I reorder one of the missed entries (put them among two others that are already displayed, than it will shown too ?!?
Is there a rule for the order of entries? If so, can I disable this rule?
Use 1.8.11 in Linux and latest (1.8.14) in Windows.
As for example I have a few structs a,b,c,d , and struct d struct is part of c.
In "C" I need to write d before c, otherwise I get compiler error. But doxygen - for some strange reason lists c only if it is located before d. So either I can compile or have a complete documentation.
I created a small example and with this example I do see all elements:
/** \file */
/** docu structure a */
struct a
{
/** docu member a */
int mem_a;
};
/** docu structure b */
struct b
{
/** docu member b */
int mem_b;
};
/** docu structure d */
struct d
{
/** docu member d */
int mem_d;
};
/** docu structure c */
struct c
{
/** docu member c */
int mem_c;
/** docu structure inside c */
struct d str_d;
};
I have used a default Doxyfile (doxygen -g).
The header file was quite large - to large to post it here - so I tried to reduce it and found the issue. The struct that will not displayed has a #code blabla statement in its doxygen header but it needs an #endcode (that was missed). Sorry for this false alarm. Thanks to albert, for this help. Asking the right questions helps too!
I have this PACKED macro, that receives a struct definition and returns it with a compiler annotation to make it packed.
For example:
/**
* ...
*/
PACKED(struct A {
/**
* ...
*/
int x;
});
I have tried several Doxygen options to include that documentation, but I've had no success so far. Closest I've come up with is this:
ENABLE_PREPROCESSING = YES
PREDEFINED = PACKED(type)=type
MACRO_EXPANSION = YES
But that messes up the struct and members' documentation (confirmed via doxygen -d Preprocessor).
Ideas?
Turns out it's a bug in Doxygen.
One possible workaround is to use #class, and so on.
I have a code
static const guint8 variable;
when I put a documentation
/**
* \var static const guint8 variable;
* \brief This is a variable
*/
static const guint8 variable;
I do not get any output in the generated documentation. However, when the same thing is done with a simple variable decleration:
/**
* \var int someothervar;
* \brief This is some other variable
*/
int variable;
it does work
is that I am making some mistake in the usage ?
Thanks for any help in advance,
- elechi
For extracting static variables you should set EXTRACT_STATIC to YES.
If the documentation is in front of the variable, you do not need (and should not use) \var
Either set EXTRACT_ALL to YES or add a comment with a #file command in your code to document the file itself.