[dojo-contributors] new doc parser and tags

Bryan Forbes bryan at reigndropsfall.net
Fri Jun 8 16:03:14 EDT 2012


Actually, that's not true. All the _setXXXAttr functions do is perform extra actions when setting a value. If a _setXXXAttr function isn't found, the property is still set on the widget. So, you don't need to know if you are able to set a property via set(): you can and should set it that way.

-Bryan

On Jun 8, 2012, at 2:27 PM, Ken Benjamin <kenbenjamin at kenbenjamin.net> wrote:

> Right, I get that.
>  
> My question is will the doc parser know that there is such a thing as set(‘myprop’, value) which points to the private _setMypropAttr() ?
>  
> If not, then the only way to know what you can set is by seeing the _setXXXAttr functions.
>  
> That’s what I was trying to getting at.
>  
> Ken
>  
> From: dojo-contributors-bounces at mail.dojotoolkit.org [mailto:dojo-contributors-bounces at mail.dojotoolkit.org] On Behalf Of Christophe Jolif
> Sent: Friday, June 08, 2012 8:24 PM
> To: dojo dev.
> Subject: Re: [dojo-contributors] new doc parser and tags
>  
> For _setXXXAttr I personally tend to now document the property itself stating that is should be get/set using Stateful get/set instead of documenting methods that users don't call.
> 
> Christophe
> 
> Le 8 juin 2012 à 18:04, Ken Benjamin <kenbenjamin at kenbenjamin.net> a écrit :
> 
> Maybe this is a dumb question but what if you have non-private _functions, like _setXXXAttr, which are private but you need to know that you can set(‘XXX’), or other uses of _function such as protected?
>  
> I guess what I’m asking is what is the default for _ prefixes and how do you override that considering there seem to be multiple intentions such as private, protected, and _setXXXAttr. All of which seem to need different kinds of documentation handling.
>  
> Ken
>  
>  
> From: dojo-contributors-bounces at mail.dojotoolkit.org [mailto:dojo-contributors-bounces at mail.dojotoolkit.org] On Behalf Of Tom Trenka
> Sent: Friday, June 08, 2012 5:29 PM
> To: dojo dev.
> Subject: Re: [dojo-contributors] new doc parser and tags
>  
> Current viewer code looks first for something to be marked by the parser as "private"; if it doesn't find that attribute and begins with "_", it assumes that it is private.  The only thing the HTML portion of the viewer does with that is to add a CSS class to the list and detail portions of that field, at which point some progressive JS will show or hide it (depending on the buttons at the top of each page which will show/hide both private fields and/or inherited ones.
>  
> -- Tom
> 
> On Fri, Jun 8, 2012 at 10:09 AM, Christophe Jolif <cjolif at gmail.com> wrote:
> Tom,
> 
> Ok for esoteric tags and even protected. But what about "private" is
> that implemented in the viewer? Is that needed in _all_ cases to hide
> something? Or are they other heuristics to determine what is hidden
> (like underscore+non documented methods? _setXXXAttr methods?...)? Or
> is that the only option?
> 
> Thanks a lot,
> --
> Christophe
> 
> 
> On Fri, Jun 8, 2012 at 4:03 AM, Tom Trenka <ttrenka at gmail.com> wrote:
> > Never got implemented but I know that when the idea of "tags" was kind of
> > released outside of what you were looking for, there was a lot of "oh,
> > tags...that's awesome.  Can we mark objects based on general categories
> > (like Ajax or DOM) with this?  Can we use it to bring some kind of easy
> > organization, so that people looking for specific functionality can find it
> > quickly?"...that kind of thing.  It was an idea that had some traction but
> > not enough for anyone to try to actually tag things that way in the API
> > docs.
> >
> > But I can see that happening if "tags" actually worked...
> >
> > -- Tom
> >
> > On Thu, Jun 7, 2012 at 6:33 PM, Bill Keese <bill at dojotoolkit.org> wrote:
> >>
> >> On Fri, Jun 8, 2012 at 12:48 AM, Tom Trenka <ttrenka at gmail.com> wrote:
> >>>
> >>> 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.
> >>>
> >> Hmm, where are things tagged as "ajax" or "DOM"?    The style guide
> >> (http://livedocs.dojotoolkit.org/util/doctools/markup#tags
> >> plus http://livedocs.dojotoolkit.org/util/doctools/markup#method-specific-tags)
> >> lists the set of expected tags (although now looking at it, I see that dijit
> >> has also been using const and readonly, so I need to add those).
> >>
> >> _______________________________________________
> >> 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
> >
> 
> 
> --
> Christophe
> _______________________________________________
> 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
> _______________________________________________
> 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/20120608/1e2d21a3/attachment-0001.htm 


More information about the dojo-contributors mailing list