Opened 8 years ago

Closed 7 years ago

#15292 closed defect (duplicate)

[meta] modules not displaying in API docs

Reported by: haysmark Owned by: haysmark
Priority: high Milestone: 1.8
Component: Documentation Version: 1.7.2
Keywords: Cc: Colin Snover
Blocked By: Blocking:

Description (last modified by 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.

Change History (14)

comment:1 Changed 8 years ago by haysmark

Milestone: tbd1.8
Owner: set to haysmark
Priority: undecidedhigh
Status: newassigned

comment:2 Changed 8 years ago by 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.

comment:3 Changed 8 years ago by haysmark

Resolution: fixed
Status: assignedclosed

In [28485]:

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

comment:4 Changed 8 years ago by haysmark

Resolution: fixed
Status: closedreopened

Oops meant Refs, not fixes.

comment:5 Changed 8 years ago by haysmark

Description: modified (diff)

comment:6 Changed 8 years ago by haysmark

Description: modified (diff)

comment:7 in reply to:  2 Changed 8 years ago by 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.

comment:8 Changed 8 years ago by bill

Cc: Colin Snover added

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

comment:9 Changed 8 years ago by 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,

Last edited 8 years ago by bill (previous) (diff)

comment:10 Changed 8 years ago by bill

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

comment:11 Changed 8 years ago by 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.

comment:12 Changed 8 years ago by 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

comment:13 Changed 8 years ago by bill

May want to close this in favor of #14980.

comment:14 Changed 7 years ago by bill

Resolution: duplicate
Status: reopenedclosed

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

Note: See TracTickets for help on using tickets.