csnover / js-doc-parse

An experimental library for parsing JavaScript files and extracting inline documentation.
31 stars 7 forks source link

old-school class declarations not tagged as class-like #47

Open wkeese opened 12 years ago

wkeese commented 12 years ago

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".

csnover commented 12 years ago

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.

wkeese commented 12 years ago

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 commented 12 years ago

Some example modules that need to get marked as constructors: