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.
Related
I want to do jsdoc with something like the following
/**
#param {string|number[]}
*/
In the above it's an array of numbers or a string, but I want an array of numbers and/or strings. I need this to work for other things like 2 different kinds of objects. Does anyone know how to do this?
If you are using Closure Compiler, you can write:
/** #param {!Array<number|string>} x */
function f(x) {}
See this example.
We have a container object for our custom classes, but JSDoc doesn't seem to like my notation for these types and comments them with
"invalid type syntax".
I am using PHP-Storm.
My JSDoc is according to this principle:
/** #type {Container['3rd'].className} */
When I change the annotation to this it seems to be valid since the comment disappears:
/** #type {Container.3rd.className} */
Why is the first property accessor syntax not considered valid in JSDoc?
The accessor using brackets is valid otherwise in Javascript code so why not in jsdoc annotations?
JSDocs #type notation is not a JavaScript expression. It is a JSDoc Namepath Expression.
If you look into these 2 links in detail you'll see a few things;
There are valid namepaths that would not be valid js:
MyConstructor#instanceMember
MyConstructor~innerMember
There are valid #type expressions that use non-JS syntax:
/** #type {(string|Array)} */
There are no mentions of using Bracket notation in either of these docs (for types/namespaces).
Inline Documentation (use Ctrl+Q to open it's pop-up) in IntelliJ IDEA (2016.3.4) is having problems when JavaDoc contains variables, like:
/** Selects the first element of this $coll.
* $orderDependent
* #return the first element of this $coll.
* #throws NoSuchElementException if the $coll is empty.
*/
Instead of parsing these variables it displays: [Cannot find macro: $coll.]. Scala API parses it correctly and changes $coll into iterable collection.
Is there a way to fix this issue in IntelliJ IDEA?
It's a known bug in IntelliJ IDEA Scala plug-in:
SCL-9720 Documentation view unreadable when #define placeholders are used
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
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.