js-doc-parse icon indicating copy to clipboard operation
js-doc-parse copied to clipboard

old-school class declarations not tagged as class-like

Open wkeese opened this issue 12 years ago • 3 comments

The code below uses lang.extend() rather than dojo.declare() to create a "class":

define([
    "dojo/_base/lang"
], function(lang){
    return lang.extend(function(){
        // summary:
        //      The constructor
    }, {
        // summary:
        //      The prototype
        func: function(a, b, c){
            // summary:
            //      The function
        }
    })
});

The parsed output is:

<object location="dojox/dtl/bill" type="function">
<properties/>
<methods>
<method name="constructor" scope="prototype" type="function" from="dojox/dtl/bill">
<parameters/>
<return-types/>
<summary><p>The constructor</p></summary>
</method>
<method name="func" scope="prototype" type="function" from="dojox/dtl/bill">
<parameters>
<parameter name="a" type="undefined" usage="required"/>
<parameter name="b" type="undefined" usage="required"/>
<parameter name="c" type="undefined" usage="required"/>
</parameters>
<return-types/>
<summary><p>The function</p></summary>
</method>
</methods>
<parameters/>
<return-types/>
<summary><p>The constructor</p></summary>
</object>

The parser clearly recognizes this as class-like at some level, hence the faux constructor method.

However, the object is marked as type="function". I would expect type="constructor" classlike="true".

wkeese avatar Jun 24 '12 11:06 wkeese

According to the ES spec, when defining a new function, it is given a prototype with a constructor property (§13.2). This doesn’t mean a function is a constructor; just like the existence or non-existence of the prototype property, it just means it may be used as a constructor. Usage of lang.extend, however, is a concrete indicator that a function is a constructor so I’ll be sure to update that code to reflect it.

csnover avatar Jun 24 '12 19:06 csnover

I see. Regardless though, seems like you should mark it as class-like if any properties are added to the prototype, or added directly to the object via this.foo = ... syntax, ex:

define([
], function(){
    return ctor(){
        this.foo = function(a){ ... };
    };
});

wkeese avatar Jun 25 '12 10:06 wkeese

Some example modules that need to get marked as constructors:

  • dojo/AdapterRegistry
  • dojo/Deferred
  • dojo/DeferredList
  • dojo/Evented,

wkeese avatar Jul 26 '12 11:07 wkeese