[doctools] YUI Doc

[Kevin Dangoor]

Yahoo has released their doc tool:

http://developer.yahoo.com/yui/yuidoc/

This is promising:

"YUI Doc is comment-driven and supports a wide range of JavaScript
coding styles."

The default output is not quite as promising, because it sounds very Java-like.

Kevin

--
Kevin Dangoor

work: http://labs.mozilla.com/
email: k...@blazingthings.com
blog: http://www.BlueSkyOnMars.com

[Robert Koberg]

On Feb 6, 2009, at 9:14 PM, Kevin Dangoor wrote:
>
> The default output is not quite as promising, because it sounds very
> Java-like.

ufff... what does this mean?

[Kevin Dangoor]

From http://developer.yahoo.com/yui/docs/YAHOO.html

static Class YAHOO

The YAHOO global namespace object. If YAHOO is already defined, the
existing YAHOO object will not be overwritten so that defined
namespaces are preserved.

Methods

augment
static void augment ( r , s , arguments )

I dare you to find an ECMAScript standard (ES4 is not a standard ;)
that mentions static classes (with static methods returning void no
less!)

However, the fact that it *knows* this is a "static method" likely
means that it could be changed to say "function", but I have not
looked at the implementation at all.

Kevin

[Robert Koberg]

On Feb 6, 2009, at 9:39 PM, Kevin Dangoor wrote:
>
> I dare you to find an ECMAScript standard (ES4 is not a standard ;)
> that mentions static classes (with static methods returning void no
> less!)
>
> However, the fact that it *knows* this is a "static method" likely
> means that it could be changed to say "function", but I have not
> looked at the implementation at all.
>

So, without looking at the code, you were able to determine how it was
used by the way it was described, hmmm...

How would you describe a function that is scoped in an instance of an
object? I probably am not explaining it well, I mean an object's method.

How would you describe a function that is not scoped in the an
instance of an object, but is a member of that object/class? (i.e. a
static method)

Sure, they are both functions -- is that enough to describe them?

best,
-Rob

[Kevin Dangoor]

On Fri, Feb 6, 2009 at 10:01 PM, Robert Koberg <r...@koberg.com> wrote:
>
>
> On Feb 6, 2009, at 9:39 PM, Kevin Dangoor wrote:
>>
>> I dare you to find an ECMAScript standard (ES4 is not a standard ;)
>> that mentions static classes (with static methods returning void no
>> less!)
>>
>> However, the fact that it *knows* this is a "static method" likely
>> means that it could be changed to say "function", but I have not
>> looked at the implementation at all.
>>
>
> So, without looking at the code, you were able to determine how it was
> used by the way it was described, hmmm...
>
> How would you describe a function that is scoped in an instance of an
> object? I probably am not explaining it well, I mean an object's method.

My point was that YUI Doc could describe it as a "static" method,
which is as close as you get to a function in Java. So, YUI Doc knows
the difference between something that's used as a function and
something that is a method.

Rather than saying

static class YAHOO

static void foobar

I'd rather say:

module YAHOO

function foobar

because that's more true to JS (granted "module" is not inherent to
JS, but is a fairly established concept with some JS libraries).

And something that is designed to behave like a class with methods can
be described that way.

[Davey Waterson]

I really prefer explicit tags, the state of the art on sniffing this
stuff out is getting better but not seen anything I'd really trust to
just get it right.

[Kevin Dangoor]

Actually, it looks like YUI Doc is just straight up tags... the tag
has the names of everything, so they aren't inferring stuff from the
code:

http://developer.yahoo.com/yui/yuidoc/#overview

So, I guess I don't have much to say at this point, other than I think
we should pick up one of these pre-existing tools and start twisting
it to our needs. JS Doc gets a bonus point for being in JS.

[Davey Waterson]

agreed

[Peter Michaux]

On Sat, Feb 7, 2009 at 5:56 AM, Davey Waterson <geek...@gmail.com> wrote:
>
> agreed

Please quote the person's name and the relevant part of the post to
which you are replying and comment below it. Those of us reading
through email readers will really appreciate it as there is not tree
structure in many email readers. In the above email it is not evident
to what you are agreeing.

Thank you,
Peter

[Davey Waterson]

2009/2/7 Peter Michaux <peterm...@gmail.com>:

>
> On Sat, Feb 7, 2009 at 5:56 AM, Davey Waterson <geek...@gmail.com> wrote:
>>
>> agreed
>
> Please quote the person's name and the relevant part of the post to

it was to kevin comment on 'just pick one and move on'