module level summaries ignored

[wkeese]

define([], function(){
    // summary:
    //      This comment gets lost
    return 123;
});

generates:

<object location="dojox/mobile/_compat" type="number">
<properties/>
<methods/>
</object>

IIUC the idea was that you could have a summary either on the module, or on the return value (and there shouldn't be duplication). But it seems only the summary on the return value works.

cc @cjolif

[AdrianVasiliu]

This also holds for "description" and "example", not only the "summary" part of the doc comments.

[csnover]

No doc parser ever supported these, someone just…started adding them to the code for some reason.

The value of the module is the thing that should have the summary on it. I don’t see being able to do both as a possible thing because the summary and description of a module are imbued by whatever the value of the module happens to be. I realise this is kind of crappy about summarising things like NodeList-fx but I’m not really sure it is important or relevant to try to support this. Thoughts?

[cjolif]

@csnover there are modules that needs to be required to enable a particular feature but for which the return value is rather meaningless. An example is dojox/mobile/compat. It needs to be included so that compatibility with desktop browser of dojox/mobile is enabled. It returns dojox/mobile for convenience and also because it adds some compatibility method on it but that return value is in most cases not really of interest. What is of interest is to know that when you include it you will enable the compatibility layer. That's why I think module documentation makes sense. Or any other solution that would allow to document this.

[AdrianVasiliu]

From dojox.mobile's point of view, what is important for this release is to have some way, any way, to get documentation for a module which doesn't define any class. So do you mean that the summary on the value of the module would work already? Or that it may work in the near future? With a freshly updated checkout of js-doc-parse, I've tried to place documentation for dojox/mobile/compat at 3 different places:

define([...], function(...){
    // module:
    //      dojox/mobile/compat
    // summary:
    //      foo1
    // description:
    //      foo1

    // summary:
    //      foo2
    // description:
    //      foo2
    var dm = lang.getObject("dojox.mobile", true);
    [...]

    // summary:
    //      foo3
    // description:
    //      foo3
    return dm;
});

And I don't get any of these "foo" pieces in the generated XML.

[wkeese]

No doc parser ever supported these

It's natural that we've never supported this before because we've never had an AMD doc parser before. But I agree that it's not needed in most cases.

I realise this is kind of crappy about summarising things like NodeList-fx

Right, this is probably the biggest issue. (@cjolif - the compat.js example is the same as the NodeList-fx example, both of those modules extend other modules.)

The other issue is the one I mentioned originally, where the module returns a scalar value or strange value:

define([], function(){
    // summary:
    //      This comment gets lost
    return 123;
});

or perhaps something like:

define([], function(){
    // module:
    //       jsonparse
    // summary:
    //     function to parse json

    return JSON ? JSON.parse : function(){ ... };
});

---

The workaround below will make the summary show up, but it loses the metadata about the module's true value.

define([], function(){
    /*=====
    return {
        // summary:
        //      does this show up?
    };
    =====*/
    return 123;
});

(In the above case it says that the module's value is an object with no properties, whereas actually it's a number.)

PS: I was also worried about plugins but I just tested and they seem to work fine, since they return a hash which can enclose a summary:

define(...
       return {
          // summary: ...

PPS: I sent mail to this list about this, but no response.

[AdrianVasiliu]

Right, the workaround you mention, Bill, does the trick for our dojox/mobile/compat, in the sense both the summary and descriptions are now in the XML. Thanks! In this particular case the lost metadata for the return value is not that much an issue, since users are not really supposed to do something with the return value of dojox/mobile/compat. Now, of course, if the API doc will include false information about the return value, this is not optimal. But at least we have a way to put documentation on our compat stuff.

[wkeese]

Good, that may be the best compromise for the 1.8 release.

And at the risk of stating the obvious, you can of course describe the real return value in the summary or description.

[wkeese]

(in progress comment)

Modules difficult/impossible to work without module level summary (or some other feature):

• exports modules (dojo/dom-attr, etc.) see #42
• dojo/main - returns the dojo/_base/kernel object but the summary is importantly different: it should say that dojo/main forces all the dojo/_base modules to be loaded
• dojo/on, dojo/has: these module return a function with other functions hanging off of it (ex: on() and on.pausable(), has() and has.add()). Thus the description for the module and the top function are different. Although even if the doc parser could remember both summaries I don't see how the viewer would display them concurrently and coherently.
• dojo/router, dojo/sniff - adding a description means losing the type information (ie, that dojo/router is an instance of dojo/router/RouterBase, that dojo/sniff returns has)