I'm using doxygen for generating HTML documentation of a C++ code. Unfortunately doxygen doesn't show undocumented method parameters in the method description. For example, with the following
/**
* Some method
* #param p1 Some param
*/
void method(const std::string& p1, const std::string& p2);
the method description will show the comment and the parameter p1 but not p2.
How can I configure doxygen to list all parameters in the method description even if not explicitly documented?
This is not possible.
Doxygen can warn you about incomplete, wrong, or missing parameter documentation though.
The relevant settings are:
WARNINGS = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = YES
Related
I have several functions that do not have a parameter or a return.
When I do something like this:
/*!
* #fn
*
* #brief ...
*
* #param None.
*
* #return None.
*/
I will get warnings about not knowing what parameter 'None.' is, and the resulting HTML documentation will highlight 'None.' as if it were a literal parameter name.
I would like to be able to explicitly say that I do not have parameters, without leaving the section blank/nonexistent.
How can I specify in the prolog (or the doxygen settings) to generate the Parameters section and use a message instead of specifying a literal parameter?
#param[in,out] is usually reserved to define the input parameters.
As you don't have any, explain this in the detailed description or using the \remark command.
I want to use doxygen to document a c-like language.
I got some issues to solve keywords which are unknown in the context.
One example, I have to use a callback function called
on timer
{
//normal c- code
}
My question is now, can I adopt doxygen to accept the new keyword?
I would like to add this keyword like a function or variable acc. to
/** This timer is used for something. */
on timer
{
}
or maybe
/** \ontimer This timer is used for something. */
on timer
{
}
The documentation of doxygen describes something with ALIASES or \xrefitem but as I understand I can only generate new sections for known types or am I wrong?
Actually I am surrounding the unknown code with a condition block out to avoid errors in the generated output.
As I understand is "on" a keyword which doxygen cannot interpret. One solution could be to declare the keyword on as a predfined macro in the doxyile by using the the PREDEFINED tag as follows:
PREDEFINED = on=
Yes, the = at the end is not a typo! This tells the preprocessor of doxygen to substitute the keyword on with a empty string. Note that you have to set ENABLE_PREPROCESSING to YES.
If the on keyword only appears before callback functions you could alternatively set the PREDEFINED macro to void:
PREDEFINED = on=void
I want Doxygen to document the code written in C-like language (PARI/GP) but having slightly different syntax. I believe Doxygen can document the entities those do not exist. It seems to be the simplest way to do the job while the programming language is not Doxygen-supported. I want something like this:
/*!
\fn foo(param,{option})
\brief some brief description here
\param[in](param) mandatory parameter description
\param[in](option) optional parameter description
*/
/*! \cond DOXYGEN_SHOULD_SKIP_THIS */
foo(param, {option}) =
{
...
};
addhelp(foo, "help message for `foo` function");
/*! \endcond */
Unfortunately, Doxygen generates the warning "documented symbol 'foo' was not declared or defined" and does not list the foo in an output HTML. Is there any way to force the Doxygen to produce the proper HTML using only the documentation blocks but not the code?
There are various options
You could write an input filter that translates your code into something that looks enough like C for doxygen to parse it (see also FILTER_PATTERNS and EXTENSION_MAPPING).
You could create a dummy C file with the function prototypes and document those instead. You could put the documentation in the C file or in your programming language if you use the approach you mentioned in the question.
If your language supports a C preprocessor, you could use doxygen's C preprocessor to hide parts of the file from doxygen, i.e.
#if DOXYGEN_ONLY
/**
\brief some brief description here
\param[in](param) mandatory parameter description
\param[in](option) optional parameter description
*/
void foo(param,option);
#endif
foo(param, {option}) { ... };
and then define the following in the config file:
PREDEFINED = DOXYGEN_ONLY
I have in a function the following variable :
97
98 UINT8 Reponse;
99 static UINT8 Initialisation = 0;
100 static DWORD StartTime = 0; //
Initialisation is also the name of one function :
void Initialisation(void)
When I clic on the hyperlink on Initialisation line 99, the block of function void Initialisation(void) is oppened.
Did any of you have an idea of what is appening ?
Thanks you for your help
Jean-Marie
See doxygen's Known Problems:
Not all names in code fragments that are included in the documentation are replaced by links (for instance when using SOURCE_BROWSER = YES) and links to overloaded members may point to the wrong member. This also holds for the "Referenced by" list that is generated for each function.
For a part this is because the code parser isn't smart enough at the moment. I'll try to improve this in the future. But even with these improvements not everything can be properly linked to the corresponding documentation, because of possible ambiguities or lack of information about the context in which the code fragment is found.
and
Doxygen does not work properly if there are multiple classes, structs or unions with the same name in your code. It should not crash however, rather it should ignore all of the classes with the same name except one.
Using Eclipse Helios:
If I define a simple Javascript function
/**
* #returns {Number}
* #param {String} arg
*/
function test(arg)
{
return 1;
}
the tags were those automatically added by Alt-Shift0J - then the inferred type for the function is:
Number test(any arg)
Parameters:
{String} arg
#returns
{Number}
Note the "any arg", despite also Eclipse also recognising the parameter is "{String} arg" later.
Nothing I've tried get the inferred type of the arg to be anything other than "any". This means calling the function with a non-String isn't detected, which is a pity.
So, is this a bug? Not supposed to work? Something I'm doing wrong?
Actually the JsDoc annotations in JSDT/Eclipse are meant for primarily two reasons(as per my comprehension, do correct me if its not the same)
For generation of documentation and
To let eclipse-JSDT-engine help the developer with auto suggest(case-specific).
so the eclipse-developers are not just cross-checking the annotation bindings with your actual code implementation until you run the js file. And again, while you run the javascript. at run time the the javadoc annotations are overlooked as mere comments.