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.
Related
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.
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:
All,
I am trying to get a handle on doxygen tags, and have encountered the following 'issue'.
In the code shown below, if I remove the #file doxytest.c from the second line, all is well. If, however, I leave it in, the output log contains this:
/Users/bp/learn/gendoxy/gendoxy/doxytest.c:10: warning: argument 'int' of command #param is not found in the argument list of foobar0(int folder)
/Users/bp/learn/gendoxy/gendoxy/doxytest.c:10: warning: The following parameters of foobar0(int folder) are not documented:
parameter 'folder'
This makes no sense to me (should it?) This is in a '.c' file, running on a MacOS.
What am I doing wrong? -- I would like to have the #file tag, and no warnings/errors from doxygen.
Or, gasp!, is this a bug?
/*!
* #file doxytest.c
*
* #author bp
* #version 0.0.1
* #copyright (2013) we be nerds,LLC
*/
/*!
* #brief void foobar0 ( int folder )
* does little to better the world.
*
* #param [in] int folder :- one small step
*
*/
void foobar0 ( int folder )
{
for (int ii = 0; ii < folder; ii++)
{
foobar1( ii );
}
}
/*!
* #brief foobar2 ( int x )
* does half of what foobar1 does.
*
*/
void foobar1( int x )
{
return( x /2 );
}
Do not include the variable type in the doxygen comment
* #param [in] folder :- one small step
Otherwise it thinks your documenting the variable 'int', and it also thinks you forgot to document the variable 'folder'.
So yes, you should keep the #file tag. Honestly I find it strange that removing the #file tag made the warning go away.
Lets say I have a function (obviously a trivial example):
public function dot(){
return implode('.', func_get_args());
}
Now I know I could modify this to be
public function dot(array $items){
return implode('.', $array);
}
but with some functions that is not an option. So, how would you document the first version of the function with a docBlock so an IDE can interpret that it can receive unlimited parameters?
I have seen some methods that use:
/**
* Joins one or more strings together with a . (dot)
* #param string $string1
* #param string $string2
* #param string $_ [optional]
* #return string
*/
public function dot($string1, $string2, $_ = null) {
return implode('.', func_get_args());
}
Which in an IDE looks like
But that feels like a hack to me, is there no way to do it just with docBlock?
[UPDATED 2015-01-08]
Old way to do this in PHPDoc was:
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html
/**
* #param int $param,...
**/
However, this is no longer supported. As of PHP 5.6 Variadic Method Parameters are a part of the PHP language, and the PHPDoc's have been updated to reflect this as of PHPDoc 2.4 if I recall correctly. This is also in the PhpStorm IDE as of EAP 139.659 (should be in 8.0.2 and up). Not sure about implementation of other IDEs.
https://youtrack.jetbrains.com/issue/WI-20157
In any case, proper syntax for DocBlocks going forward for variadic parameters is:
/**
* #param int ...$param
**/
As Variadics are implemented in PHP 5.6 PHPDocumentor should support the following syntax as of version 2.4.
/**
* #param Type ...$value
* Note: PHP 5.6+ syntax equal to func_get_args()
*/
public function abc(Type ...$value) {}
This should be the correct way to describe such a signature. This will likely be included in PSR-5. Once that is accepted IDE's should follow to support this "official" recommendation.
However, in the mean time some IDE's have an improved understanding of what they consider correct. Hit hard on the IDE vendor to support the offical PHP syntax that is supported as of 5.6 or use whatever works in the meantime.
In php the concept of valist or list of "optional arguments" does not exist.
the $_ variable will just contain, here the third string you give.
The only way to allow an array OR a string is to test the first argument with is_array()
public function dot($arg1){
if(is_array($arg1)){
return implode('.',$arg1);
}
else if $arg1 instanceof \Traversable){
return implode('.',iterator_to_array($arg1));
}
else{
return implode('.',func_get_args());
}
}
Now that you handled the behaviour you want, you have to document it. In php, as overloading is not allowed, a convention is to use "mixed" as a type if you want to provide multiple types.
/**
*#param mixed $arg1 an array, iterator that will be joined OR first string of the list
*#return string a string with all strings of the list joined with a point
*#example dot("1","2","3"); returns 1.2.3 dot(array(1,2,3)); returns 1.2.3
*/
Moreover, according to phpdocumentor documentation you can declare sort of valist with
/**
*#param string ... list of strings
*/