[meta] modules not displaying in API docs

[haysmark]

There are a few modules that are not listed in the api.xml or do not have their docs completely listed. For instance, it seems that the API parser is not happy about scripts like dijit/registry that define() an object without formally declare()ing it as well.

• dijit.registry: does not show in list. preview shows no docs.
• dijit._Widget and _WidgetBase: does not show in list, presumably because it is private, but is generated.
• dijit.Dialog: the multiple inheritance seems to throw it off. looks fine in preview, but nothing shows in entry live.

[bill]

But, Colin is completely rewriting the API parser. Or are you talking about the new parser? Theoretically dijit/registry will be fine with his new parser.

dijit/registry isn't using declare because it's not a "class", but rather just a bunch of related methods.

[haysmark]

In [28485]:

Add doc comments to dijit/registry.js so it appears in api.xml. Fixes #15292.

[haysmark]

Oops meant Refs, not fixes.

[haysmark]

Replying to bill:

But, Colin is completely rewriting the API parser. Or are you talking about the new parser? Theoretically dijit/registry will be fine with his new parser.

dijit/registry isn't using declare because it's not a "class", but rather just a bunch of related methods.

Yes widgets like Dialog and the properties seem beyond repair, but it can't hurt to simplify the doc parser's job.

[bill]

I just suspect that [28485] is complicating the new doc parser's job rather than simplifying it. cc'ing Colin to take a look.

[Colin Snover]

Hi Mark,

Thanks for trying to help but these changes actually make it harder for the new parser to do its job. There’s actually already no problem with parsing the structure of dijit/registry, here’s output from the parser against 1.7.2:

    <javascript>
        <object location="dijit/registry" type="object">
            <properties>
                <property name="length" type="number" />
                <property name="_hash" type="object" />
            </properties>
            <methods>
                <method name="hasOwnProperty" type="prototype">
                    <parameters>
                        <parameter name="V" type="string" usage="required" />
                    </parameters>
                    <return-types>
                        <return-type type="boolean" />
                    </return-types>
                </method>
                <method name="toString" type="prototype">
                    <parameters>
                        <parameter usage="required" />
                    </parameters>
                    <return-types>
                        <return-type type="string" />
                    </return-types>
                </method>
                <method name="add" type="normal">
                    <parameters>
                        <parameter name="widget" usage="required" />
                    </parameters>
                    <return-types />
                </method>
                <method name="remove" type="normal">
                    <parameters>
                        <parameter name="id" usage="required" />
                    </parameters>
                    <return-types />
                </method>
                <method name="byId" type="normal">
                    <parameters>
                        <parameter name="id" usage="required" />
                    </parameters>
                    <return-types>
                        <return-type />
                    </return-types>
                </method>
                <method name="byNode" type="normal">
                    <parameters>
                        <parameter name="node" usage="required" />
                    </parameters>
                    <return-types>
                        <return-type />
                    </return-types>
                </method>
                <method name="toArray" type="normal">
                    <parameters />
                    <return-types>
                        <return-type type="Array" />
                    </return-types>
                </method>
                <method name="getUniqueId" type="normal">
                    <parameters>
                        <parameter name="widgetType" usage="required" />
                    </parameters>
                    <return-types>
                        <return-type type="string" />
                    </return-types>
                </method>
                <method name="findWidgets" type="normal">
                    <parameters>
                        <parameter name="root" usage="required" />
                    </parameters>
                    <return-types>
                        <return-type type="Array" />
                    </return-types>
                </method>
                <method name="_destroyAll" type="normal">
                    <parameters />
                    <return-types />
                </method>
                <method name="getEnclosingWidget" type="normal">
                    <parameters>
                        <parameter name="node" usage="required" />
                    </parameters>
                    <return-types>
                        <return-type />
                        <return-type type="null" />
                    </return-types>
                </method>
            </methods>
        </object>
    </javascript>

So, please don’t “fix” the code to make it “easier” for the parser, since the parser doesn’t need this help and it actually will make things worse in a lot of cases since you’re essentially adding untested code to the codebase.

Cheers,

[bill]

Well, the output above is missing the summary of the dijit/registry module: "Registry of existing widget on page, plus some utility methods."

[Colin Snover]

I know that the comments aren’t included yet. That part isn’t done, as I mentioned in the last status update to the ML. But dijit/registry does not show up *at all* with the old parser (no structure, no nothing), which is what this hack was trying to fix.

[bill]

In [28535]:

revert [28485] as it actually makes things more difficult for the new doc parser (especially since it's accessing an undefined variable named "declare") , refs #15292 !strict

[bill]

May want to close this in favor of #14980.

[bill]

Duplicate of #13101.
Closing this because we've been putting module updates in #13101.