imposed structure on javascript

[wilco]

I've recently started using YUIDoc for one of my projects. I've worked with documentation tools from other languages before and I must say this is the best JavaScript documentor I've seen. So, great job there. But what surprised me, and what is actually putting me off a bit is the way YUIDoc is imposing the classical OOP architecture (modules, classes, properties, methods, etc.) on top of JavaScript.

The reason is that I'm having some difficulty expressing my architecture in the classical OOP terms is that YUIDoc seems to be based on the assumption that javascript developers are still exclusively thinking in terms of classes. Many of the modules I write don't have classes. They either return an object or a function. From what I gather, YUIDoc wants me to label these as static classes. For objects that seems a very round about way of saying what it actually is. And for functions I can't fit that description at all. The closest thing would be a method that does it's job without having it's 'this' value set.

Now clearly, if you go back to theory, a class is just a description of the things curtain objects have in common. Even though there is no syntax for it, certain function (including constructors) can be said to return objects of a specific class. So describing those classes makes sense. But what I don't think makes too much sense is to then document that function as if it's actually a class. It's just not, it's a function that returns an object of a certain class. Considering all other JavaScript documentors have done pretty much the same thing, it may just be me. But it seems to me that JavaScript isn't moving in the direction of a classical OOP language, and it may be worth a discussion to figure out if we shouldn't take a different approach to documentation as well.

[Dav Glass]

Yes YUIDoc makes assumptions because it's geared toward working with
YUI which is class/OOP based in design.

But, just because you label something a class doesn't mean it's
actually a class. If you don't use the @constructor tag, then it's not
technically a class. Although YUIDoc labels it that way because from
the users perspective that's what they are expecting.

If you have any suggestions on how to make it easier, please file an
issue or even better a pull request with the changes ;)

I'm totally open to changes, but they need to be vetted and useful :)

Dav

--
Dav Glass
davg...@gmail.com
blog.davglass.com


+ Windows: n. - The most successful computer virus, ever. +
+ A computer without a Microsoft operating system is like a dog
without bricks tied to its head +
+ A Microsoft Certified Systems Engineer is to computing what a
McDonalds Certified Food Specialist is to fine cuisine +

> --
> You received this message because you are subscribed to the Google Groups
> "yuidoc" group.
> To post to this group, send email to yui...@googlegroups.com.
> To unsubscribe from this group, send email to
> yuidoc+un...@googlegroups.com.
> To view this discussion on the web visit
> https://groups.google.com/d/msg/yuidoc/-/l4HM1SlaCAAJ.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>