I'm currently generating documentation for a pure C project.
In a file utilities.h file I have this:
/**
* #defgroup LOG_LEVELS Different levels of log file granularity
*
* \addtogroup LOG_LEVELS
* #{
* Each logging routine has a mandatory parameter defining the logging level
* of the current logging function call. Only if that level is less or equal
* to one of those predefined levels by the constants given here, that call
* will actually be logged. These constants are also used to set the current
* logging level in #currentLogPrio .
**/
#define LOGPRIO_ALWAYS 0 /**< always log this, although no error */
#define LOGPRIO_FATAL 0 /**< fatal errors */
#define LOGPRIO_ALERT 100 /**< alerts */
#define LOGPRIO_CRITICAL 200 /**< critical, but not fatal errors */
#define LOGPRIO_ERROR 300 /**< normal errors */
#define LOGPRIO_WARNING 400 /**< warnings */
#define LOGPRIO_NOTICE 500 /**< notices */
#define LOGPRIO_INFO 600 /**< informational texts */
#define LOGPRIO_TRACE 700 /**< tracing */
#define LOGPRIO_DEBUG 800 /**< debugging information */
/** #} **/
In the associated utilities.c file the static variable currentLogPrio is defined:
/**
* #var currentLogPrio
* #brief Current setting of the logging level.
*
* Only if a logging routine was called with its log level parameter set to a
* value less than or equal to the current logging priority the actual call of
* a logging routine will be written to the log.
**/
static logPrio_t currentLogPrio = LOGPRIO_ALWAYS;
Now, when I run doxygen on the complete project, I get the following warning:
...
Preprocessing utilities/logUtilities.c...
Parsing file utilities/logUtilities.c...
Preprocessing utilities/logUtilities.h...
Parsing file utilities/logUtilities.h...
...
Generating code for file utilities/logUtilities.c...
Generating code for file utilities/logUtilities.h...
...
Generating docs for file utilities/logUtilities.h...
Generating call graph for function logErrcode
Generating call graph for function logMsg_alert
Generating call graph for function logMsg_always
Generating caller graph for function logMsg_always
Generating call graph for function logMsg_critical
Generating call graph for function logMsg_debug
Generating caller graph for function logMsg_debug
Generating call graph for function logMsg_error
Generating caller graph for function logMsg_error
Generating call graph for function logMsg_fatal
Generating caller graph for function logMsg_fatal
utilities/logUtilities.h:136: warning: explicit link request to 'currentLogPrio' could not be resolved
Both files are part of the doxygen documentation as you can see from doxygens output and have the #file tag included. I also know that the #var tag for the static variable is not needed, but I get the same errors with or without this tag.
So, how can I link to that static variable?
Best regards and thanks in advance
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
I am using Doxygen to document a C++ project which is becoming bigger and bigger and I have been wondering how I could make Doxygen a build requirement for the project. In other words, I would like my build process to fail and stop if any class/method/etc. has not been successfully documented for Doxygen. I use make for building.
For example, I would like this to fail (i.e. not build):
/**
* #bbrief Oops, tag does not exist, warning is issued and hence build fails.
*/
void f()
{
// Do something...
}
/**
* #brief Main function for program X
*
* #return End of execution status.
*
* ...
*
*/
int main()
{
f();
return 0;
}
but this to build:
/**
* #brief Okay, this is fine.
*
*/
void f()
{
// Do something...
}
/**
* #brief Main function for program X
*
* #return End of execution status.
*
* ...
*
*/
int main()
{
f();
return 0;
}
I have tried searching the Internet for this kind of feature but so far have found nothing.
In most cases the documentation is generated but due to the warnings it is incomplete. I see a few possibilities:
For this purpose the configuration setting WARN_AS_ERROR is present (see: http://www.doxygen.nl/manual/config.html#cfg_warn_as_error). Possible disadvantage is that process stopes directly when a warning is encountered.
catch the warnings in a file and count them / see if the file is
empty and based on this decide whether the build was successful or
not.
Edit
As noted by #inkychris the WARN_AS_ERROR has, as of doxygen version 1.9.0, the possibility FAIL_ON_WARNINGS. From the documentation:
WARN_AS_ERROR
If the WARN_AS_ERROR tag is set to YES then doxygen will immediately stop when a warning is encountered. If the WARN_AS_ERROR tag is set to FAIL_ON_WARNINGS then doxygen will continue running as if WARN_AS_ERROR tag is set to NO, but at the end of the doxygen process doxygen will return
with a non-zero status.
Possible values are: NO, YES and FAIL_ON_WARNINGS.
How do i group all the functions, classes, defines etc of a file?
Example file:
/*!
* \file
* \ingroup myGroup
*/
/*!
* this is my function.
*/
int myfunc();
Now, if look at the output, only the file is added to that group. The function is not. i need to add \ingroup myGroup to that file to add it. Can that be done by brackets{} or any way else?
Thans to alberts persistence i found a working way:
/*!
* \file
* this is my testfile
* \ingroup UnitName
* \addtogroup UnitName
* \{
*/
/*!
* this is my function.
*/
int myfunc();
/*! \} */
This generates the wanted output. The File andthe function is added correctly.
It does not work with \ingroup. It puts the function into the files section (i upgraded to the latest version of doxygen with the same outcome.
If I use "after the member" documentation for function parameters, for example, use //!< after each parameter, instead of #param in the header, the "Parameters" section is always placed after "Return" in the generated output file.
Is is possible to define the order so that "Parameters" will be placed before "Return"?
/**
*****************************************************************************************
* #brief Test API
*
* #usage This API can be called at any time
*
* #return 0 if successful; or 1 if failed
****************************************************************************************/
int TestAPI(
int argument1, //!< first argument
int argument2 //!< second argument
);
I've just tried out your code with Doxygen 1.7.5.1, and confirmed that with your code, the Parameter list in the output comes after the description of Return.
This is a shame, as the //!< style is much nicer than having to re-state the names of all the parameters with #param:
/**
*****************************************************************************************
* #brief Test API
*
* #usage This API can be called at any time
*
* #param argument1 first argument
* #param argument2 second argument
*
* #return 0 if successful; or 1 if failed
****************************************************************************************/
int TestAPI2(
int argument1,
int argument2
);
I had a look in the Doxygen Bugzilla bug database, to see if it was a relatively recent bug (as then you could try reverting to an older installation).
I believe you've found Doxygen Bug 316311: 'parameter documentation after return documentation by using inline comments', which was reported in September 2005, and hasn't been fixed.
So, sadly, I'm afraid the answer to your question Is is possible to define the order so that "Parameters" will be placed before "Return"? is almost certainly No.
Edit
I've just added a note to Doxygen Bug 316311, asking for it to be changed to Status=CONFIRMED.