The inline "doc hint" for return value type is not taken into account.

[pruzand]

Hi,

It seems the current parser does not take into account the "documentation hint" that may be specified for the return value.

For ex:

    bar : function(){
        return "asdf";
    },
    getBarFoo:function(){
        // summary:
        //      adf askdfj asdf asdf asdf 
        var a = this.bar();
        return a;   // String
    },

which gives:

  <method name="bar" scope="prototype" type="function" from="dojox/geo/openlayers/Map">
    <parameters/>
    <return-types>
      <return-type type="string"/>
    </return-types>
  </method>
  <method name="getBarFoo" scope="prototype" type="function" from="dojox/geo/openlayers/Map">
    <parameters/>
    <return-types>
      <return-type type="undefined"/>
    </return-types>
    <summary>adf askdfj asdf asdf asdf</summary>
  </method>

Also, if the keywod "returns" is used, it adds an extra any element:
bar : function(){
// summary:
// adf asdf alsfqwe
// returns:
// something interesting.
return "asdf";
},

gives:

  <method name="bar" scope="prototype" type="function" from="dojox/geo/openlayers/Map">
    <parameters/>
    <return-types>
      <return-type type="any"/>
      <return-type type="string"/>
    </return-types>
    <return-description>something interesting.</return-description>
    <summary>adf asdf alsfqwe</summary>
  </method>

cc @cjolif

[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