I'm documenting my code and can't make doxygen to pick up
functions inside nested namespaces.
Googling around i didn't see anyone facing this problem, sorry if a duplicate.
namespace n1 {
/*! #addtogroup n1
*#{
*/
/**
* n2 is...
*/
namespace n2 {
/**
* n3 is...
*/
namespace n3 {
/**
* function does...
*/
static inline
int
find() { }
}
}
/*#}*/
}
In the resulting documentation (html) I see all namespaces (n1, n2, n3) but don't see any functions (e.g. find() ). The page corresponding to n3 namespace contains none.
I also tried EXTRACT_ALL build flag, does not seem to help.
p/s/ doxygen is generated using Doxygen GUI for OS-X.
You need to set EXTRACT_STATIC = YES in your Doxyfile.
The comment on EXTRACT_ALL states, "Private class members and static file members will be hidden unless the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES"
I've tested with your example and setting EXTRACT_STATIC = YES and the find function is visible in the resulting documentation.
Related
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 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.
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.
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
*/
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.