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
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.
I see that some IDE like (PHPStorm) can read phpDoc in code I mean when i do
/** #var SomeType $variable */
$var = $this->diffrentWayToCreateAnObject('SomeType');
or my best
/** #var SomeType $val */
foreach($item in $key => $var) {
}
PHPStorm knows that $var is an instance of class SomeType. This is very handy when I work using diffrent frameworks cause I don't always create an object using new keyword
Can I make my eclipse to read this ?
I've been told by several other Eclipse users before that PDT does recognize this usage of #var, although I myself have never actually seen it succeed.
One syntax change that might help your usage would be to use a fully qualified namespaced name for your data type:
/** #var \SomeType $var */
$var = ...
Note also that I corrected your variable name in your example. If that example is actually your code verbatim, the variable name mismatch ($variable vs $var) would explain why the #var did not work.
I see the same two issues in your foreach() example too, "SomeType vs \SomeType" and "$val vs $var).
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.