tags not picked up

[wkeese]

From dijit/_WidgetBase.js, the [const] on:

// id: [const] String
//      A unique, opaque ID string that can be assigned by users or by the
//      system. If the developer passes an ID which is known not to be
//      unique, the specified ID is ignored and the system-generated ID is
//      used instead.
id: "",
_setIdAttr: "domNode",  // to copy to this.domNode even for auto-generated id's

does not seem to get picked up. Output is:

<property name="id" scope="prototype" type="string" from="dijit/_WidgetBase">
<summary>
A unique, opaque ID string that can be assigned by users or by the system. If the developer passes an ID 
which is known not to be unique, the specified ID is ignored and the system-generated ID is used instead.
</summary>
</property>

Same for [readonly], [protected], etc., on srcNodeRef and baseClass.

[csnover]

Where do you expect these to go? They don’t show up in details.xml in 1.5 either.

[wkeese]

Oh, that's surprising I assumed scalar tags were showing up in 1.5, because Neil told me to write tags for scalar attributes like that.

I looked at the 1.5 api.xml file and it uses a tags attribute for random tags on methods, and a private attribute for private methods:

<method name="onMouseUp" scope="prototype" tags="callback">
<method name="postscript" constructor="postscript" scope="prototype" private="true">
<method name="_getAltViewNode" scope="prototype" tags="protected." private="true" privateparent="true">

IIRC Neil's code started out only handling specific tags and then Pete tried to expand it to handle any tags, so that explains the inconsistency.

So, to answer your question, I suppose that for consistency both scalar attributes and method attributes should be handled with tags="..." for all tags:

<property name="id" scope="prototype" type="string" from="dijit/_WidgetBase" tags="const">
<method name="postscript" constructor="postscript" scope="prototype" tags="private">

cc'ing @ttrenka in case he has a different preference

[ttrenka]

IIRC the only things made actual attributes from that kind of tagging in the previous parser was the private attribute; I think that existed before the tags implementation.

From what I remember, if a tags attribute actually showed up, it was basically whatever was defined in that attribute (which you can probably see with the tags="protected." in the _getAltViewNode, above.

I have no preference, though the private attribute is used pretty heavily in the current API viewer. I just need to know what the final implementation will be so I can handle it.

[csnover]

Well I added the private tag attribute in df733f7, I don’t know why the other tags are useful for at the moment though. Does the viewer actually do something with any other ones (not “can we add this” but “does it already exist”)? If not I would just opt to leave them out for now and do something else at phase 2.

[wkeese]

Thanks, the private tag looks like it's working to me. I'll assume your question above is for @ttrenka; as far as I can tell the current viewer sadly isn't showing the data for other tags like const or readonly or protected. Possibly the were showing up from preview.php.

[wkeese]

PS: I meant to say that private tags are working for methods. I'm not seeing the tags handled for scalars, such as in dijit/_editor/RichText.js:

// isClosed: [private] Boolean
isClosed: true,

which produces:

<property name="isClosed" scope="prototype" type="boolean" from="dijit/_editor/RichText"/>

[ttrenka]

I don’t know why the other tags are useful for at the moment though. Does the viewer actually do something with any other ones (not “can we add this” but “does it already exist”)

There's code halfway sketched for it in the current viewer, but I never implemented it in full mainly because there was some major misunderstandings about what those tags actually meant. I think Bill assumed that it was for typical compiled language attributes (like protected, static, etc), and quite a few others thought it was to enable some kind of tag-cloud markings.

If you have a lucid implementation of tags, I can certainly add it very quickly; its just a matter of deciding where they should go in the generated pages, and what they really represent.

[csnover]

Since the tags were not actually in use before I would prefer to focus on functionality that used to exist but is broken, so I am going to defer this to the future.

[wkeese]

This is in my patches to the parser, https://github.com/wkeese/js-doc-parse/commit/9ca039cf4433c865716d891a8cf926bc37428fb1 and https://github.com/wkeese/js-doc-parse/commit/7d5f3bb4342f32720e890f0902be638b9454a5cc