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.
Related
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).
I woul like to reference method's parameters in the documentation text,
but have no idea how to do it.
In .NET world we use tag paramref
Just as an example:
/** Send email with the specified #paramref body to the addesses given in #paramref to.
#param body Just a plain text or teamplate-aware text.*/
def SendEmail(body: EmailBody, to: EmailAddress*) = ???
How is it done in Scala?
You can make reference in Scaladoc similarly to Javadoc. According to the documentation for javadocs:
{#code foo}
and
<code>foo</code>
But XML looks ugly and not readable, prefer to use {#code foo} instead.
I think you should find everything you need in https://docs.scala-lang.org/style/scaladoc.html. Do a string search for "param name".
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.
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 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