The inline "doc hint" for return value type is not taken into account. about js-doc-parse

[pruzand]

cc @wkeese

[dmandrioli]

It seems that using only the "returns:" keyword gives an extra null or object return type:

    <return-types>
      <return-type type="Number" />
      <return-type type="null" />
    </return-types>

or

    <return-types>
      <return-type type="Number" />
      <return-type type="object" />
    </return-types>

[pruzand]

In order to start the doc update of the source files, I would like to know what's planned to support return type documentation.
According to http://livedocs.dojotoolkit.org/util/doctools/markup,

• the returns keyword "does not include a type, which should appear within the function"
• "Because a function can return multiple types, the types should be declared on the same line as the return statement"

Do you plan to follow these guidelines ? In particular, that the "returns" key should not include the return type ?

[cjolif]

we have tons of returns: Type, so I hope this will still be supported!

[wkeese]

dojodoc.js::generateMetadata() has code for the doc-hints:

else if (value.raw.type === 'ReturnStatement') {
    // Comment at the end of the first line of the return statement, if one exists
    candidate = /^[^\n]*\/\/(.*?)\n/.exec(util.getSourceForRange(value.raw.range));

The problem is that generateMetadata() isn't called on return statement at all. Reproducible with a simple test case like:

define([], function(){
    return function(){
        return "foo";   // dojo/NodeList
     };
});

Looks like a problem in esprimaParser.js: Nothing inside the function is getting processed. (I can add a for() loop outside the function and see ForStatement getting called, but if the for() loop is inside the function ForStatement isn't called.)

[neonstalwart]

i think this original issue would be fixed by d86cc3a in #80