[dojo-contributors] new doc parser and tags

Ken Benjamin kenbenjamin at kenbenjamin.net
Sat Jun 9 02:39:45 EDT 2012


Coming at it from a pragmatic user-oriented perspective without applying a
particular ‘philosophy’ to the topic, I would want the API viewer to simply
show me what is possible and safe for me to use i.e. the public properties,
methods, and events for that module.



I agree that how I use (or misuse) those APIs is my problem and best left
to tutorials and the reference guide.



Of course, that brings up the (off topic) point of needing a really good
Getting Started guide. The fact that I’ve been building Dojo code (entirely
programmatically) for 6 months now without understanding that a) Stateful
is the base for all dijits; b) set() works on properties without a
_setXXXAttr function; c) appreciating the connection between set() and
watch(), speaks partly to whatever failings I might have but I think also
to the existing documentation.



As it stands right now, the best way I have found to learn Dojo is to open
the source and read the comments and, usually, the code, to every function
I want to use. For dijits that means tracing a tree of inheritance that is
confusing at best. It may seem excessive but at least I’m starting to
understand how it all works (and making far less mistakes).



Ken



*From:* dojo-contributors-bounces at mail.dojotoolkit.org [mailto:
dojo-contributors-bounces at mail.dojotoolkit.org] *On Behalf Of *Tom Trenka
*Sent:* Saturday, June 09, 2012 3:19 AM
*To:* dojo dev.
*Subject:* Re: [dojo-contributors] new doc parser and tags



It's not a dumb question, and sorry...I would have answered earlier but
today was a travel day for me.



The biggest issue (to me) is whether or not you try to carry over
non-Javascript idioms into both code and documentation.  If you are writing
widgets, then it is essential that you know how the whole get/set thing
works.  However, I'm also a firm believer in the idea that API
documentation should be just that: a human-readable form of the way
something works *as implemented in Javascript*.  To be honest, this has
been the biggest problem with creating some kind of auto-generated API
documentation.



Colin's current approach is a step closer to realizing the goal of being
able to reflect on the actual code and produce some kind of view that can
be interpreted by a clever viewer.  But I still get the sense that we're
looking at trying to apply a particular paradigm to that view...



My own short answer is that API documentation (the kind that actually
inspects source and creates a view of it) should be pure JS, and things
like the reference guide and tutorials should explain the "why" of the
approach.  In other words, API should show the raw construct, regardless of
whether or not the people trying to use the API documentation has
expectations or not.



Does that help?



Cheers--

Tom



On Fri, Jun 8, 2012 at 11:04 AM, Ken Benjamin <kenbenjamin at kenbenjamin.net>
wrote:

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.dojotoolkit.org/pipermail/dojo-contributors/attachments/20120609/053b8674/attachment.htm 


More information about the dojo-contributors mailing list