[dojo-contributors] new doc parser and tags

Tom Trenka ttrenka at gmail.com
Thu Jun 7 11:48:21 EDT 2012


There's a bit of history there, and IIRC Colin and Bill are trying to hash
out an answer to this question in the parser code at the moment.

The short answer is that the original version of the parser did not
distinguish between public and private, and so an assumption was made in
various iterations of the viewer that anything prefixed by "_" was
considered private.  The idea of designating something as "protected" was a
concept introduced primarily by Bill, and the changes made to the original
parser were somewhat incomplete; sometimes there would be a "tags"
attribute that simply listed any and all tags put on something...and how
they were listed was very inconsistent.

Same thing with assuming anything beginning with "on" was considered an
event handler; there was no way to designate something that way.

If I get a consistent way of seeing tags, and can come up with consistent
ways of displaying them in the viewer, I'm more than happy to.  However,
the usage of tags seems to have generated a bit of confusion; some see it
as a way of marking fields using compiled language modifiers (i.e. static,
protected, const), and some see it as a way of implementing a tag cloud
(for instance, tagging something as "ajax" or "DOM").  We'll probably need
to have this clarified.

Cheers--
Tom


On Thu, Jun 7, 2012 at 9:58 AM, Christophe Jolif <cjolif at gmail.com> wrote:

> I don't see any answer to Patrick's question but I have an extension
> to his question:
>
> 1/ the Dojo Doc Documentation says underscore methods are protected
> 2/ the Dojo Code Documentation (Styleguide) says they are private
>
> Which one is right?
>
> Also do we need to put a private tag to force an underscore method to
> be hidden or not (*)? From 1/ I would say yes? Is that true also if
> the method has no documentation at all?
>
> PS: in all cases the method appears in the result of the doc parser,
> so I suspect this time (on the contrary of Patrick's question) this is
> more a question for the viewer side (Tom?).
>
> Thanks,
>
> --
> Christophe
>
> On Tue, Jun 5, 2012 at 4:42 PM, Patrick Ruzand <pruzand at gmail.com> wrote:
> > Hello,
> >
> > I have a question about how the new doc parser supports the various
> > tags defined here:
> > http://livedocs.dojotoolkit.org/util/doctools/markup#tags
> > that is, the visibility tags but also the method-specific tags.
> > Unless I missed something, my recent tests today showed the tags don't
> > appear in the xml output.
> > Is it something planned for the release ? or is there an option to
> > enable them in the output ?
> >
> > Thanks
> >
> > --
> > Patrick
> > _______________________________________________
> > dojo-contributors mailing list
> > dojo-contributors at mail.dojotoolkit.org
> > http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
> _______________________________________________
> dojo-contributors mailing list
> dojo-contributors at mail.dojotoolkit.org
> http://mail.dojotoolkit.org/mailman/listinfo/dojo-contributors
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.dojotoolkit.org/pipermail/dojo-contributors/attachments/20120607/c5bb847b/attachment-0001.htm 


More information about the dojo-contributors mailing list