Doyxgen onetime macro expansion / expansion command - macros

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

Related

Using " 's " after a Doxygen identifier

I'm writing the documentation of a C project using Doxygen.
In the documentation of a function, one can refer to an argument of the function using \p. I want to use the " 's " possessive idiom in my text, e.g. writing the object's name. Here is a code sample that triggers the issue:
/**
* #file
* #brief Main C entry point
* #author Vincent Siles
*/
#include <stdio.h>
typedef struct {
int foo;
int bar;
} foobar;
/**
* #brief blabla
*
* toto \p in's field foo.
* toto \p in 's field foo.
*
* #param in input
*/
void test(foobar *in)
{
printf("%d %d\n", in->foo, in->bar);
}
int main(void)
{
foobar xxx = { .foo = 0, .bar = 0};
test(&xxx);
return 0;
}
The generated HTML features:
<p>blabla </p>
<p>toto <code>in's</code> field foo. toto <code>in</code> 's field foo.</p>
As you can see, both <code> parts are unsatisfactory: the first one has the " 's " inside it and it feels wrong, and the second one has an additional space.
In this case, I could rephrase into the field of \p in, but that's not always possible. Is there a way to output <code>in</code>'s field ?
For the record, I'm using version 1.8.11, and I have this issue with the default configuration, created by doxywizard + optimize for C/PHP. The full configuration can be found here.
It is not possible with the \p command.
However, as a workaround you can use `in`'s instead of \p in's.
But note that it might look a bit weird since the <code>in</code> part will use a different font as the 's which therefore might appear bigger or smaller:

Is it possible for Doxygen to exclude undocumented functions from generated XML?

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.

How to get #borrows tag working in JSDoc

I have been having a hard time getting the #borrows tag working in JSDoc. I have been trying to get the documentation from one function and us it as documentation for a second function. But I don't seem to be able to even get a simple example working!
/**
* This is the description for funcA
*/
var funcA = function() {};
/**
* #borrows funcA as funcB
*/
var funcB = function() {};
I was expecting this to output documentation for both functions with both exactly the same. However only funcA is only has a description.
The #borrows tag doesn't seem to work directly on a symbol, but only indirectly. For example I had:
/** does amazing things */
function origFunc = function() {};
/**
* #borrows origFunc as exportedFunc
*/
exports.exportedFunc = origFunc;
but I, like you, got nothing useful in the generated doc.
That is because, it seems, that the #borrows tag operates on a container. (If you'll notice in the examples the #borrows tag is on the "util" module/namespace, not the renamed symbol.)
So this worked for me:
/** does amazing things */
function origFunc = function() {};
/**
* #borrows origFunc as exportedFunc
*/
exports = {
exportedFunc: origFunc,
}
Seems like a bug in #borrows though. (Or at least a bug in the documentation.)
I recently had a usage of it, what I was trying to do is to create a module and add some functions to it. The problem is that I don't have anything directly related to this module, since the export is just a line. Here's how I ended up with using #borrows.
/**
* A typehead with options filtered by user input.
*
* #module Typehead
* #borrows Typehead
* #borrows TypedOption
* #example
* <Typehead />
*/
export { default } from './Typehead'
In this case, Typehead will be borrowed in either Function or Classes section of module page depending on the kind of Typehead, and it will be displayed under #example render.
Note: However #borrows will add some extra entries to the system, after some experimentation, maybe #see is a better use.

Make Doxygen document a struct/class defined inside a macro call

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.

doxygen function parameter documentation (//!< vs #param)

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.