YUI Doc: A New Tool for Generating JavaScript API Documentation

By Eric MiragliaDecember 8th, 2008

We’re pleased today to release the first public version of YUI Doc, a python-based documentation tool that generates API documentation for JavaScript code. YUI Doc was developed by Adam Moore, one of the principal engineers on the YUI project since its inception, to support YUI’s API-level documentation.

Those familiar with JavaDoc, JSDoc, or the JsDoc Toolkit (the latter superceded JSDoc, which no longer sees active development) will find YUI Doc’s conventions familiar. It is a comment-driven system in which documentation is parsed from comment blocks that describe the structure of your code. Unlike some analagous systems, YUI Doc is designed to work purely from comments; as a result, there is no idiom or code pattern with which the tool is incompatible.

YUI Doc’s principal organizational structures are these:

  • Project: The project is the top-level bucket into which a set of documentation is grouped. In the case of YUI’s documetnation, YUI itself is the project.
  • Module: A module is used to group pieces of code that relate to a functional unit. For example, in YUI the Drag and Drop Utility is a module; the AutoComplte Control is a module; etc. Modules can depend on one another and can be further subdivided into submodules (in YUI 3, we make extensive use of submodule structures to deliver the smallest possible code payloads).
  • Class: Classes (and inner classes) are used to describe objects that function as instantiable or static classes in JavaScript. YUI Doc also supports concepts like augmentation, allowing you to document the inheritance structures that characterize your object-oriented applications.
  • Methods and Properties: Methods and properties are used in the conventional sense to document class members.
  • Events: We’ve added the event construct to YUI Doc to support YUI’s Custom Event infrastructure. Where you are building modules that publish events with well known parameters, YUI Doc can help you expose that information through this construct. (As a simple example, when a date is selected in the YUI Calendar Control, the selectEvent is fired.

YUI Doc is most likely to be of interest to those who are building library-style code to be used by other developers. Because it requires in-line documentation, it is only appropriate to use YUI Doc in combination with a minification tool (like Douglas Crockford’s JSMin or Julien Lecomte’s YUI Compressor). A common scenario would be to incorporate YUI Doc into an existing continuous-build process to generate and publish documentation at build time; your code might be concatenated and version-stamped by Ant, verified by JSLint, documented by YUI Doc, and then minified by YUI Compressor.

YUI and Git; photo by Dav GlassYUI Doc joins YUI Compressor in the portfolio of build-time processes that we’re making available as part of the YUI project. We look forward to your feedback on this beta release. The source code for YUI Doc has been published on GitHub; if you’d like to get involved in YUI Doc development, we invite you to check out the source (instructions here), sign a CLA, and join us in making this the best documentation engine available for serious frontend engineers.

Footnote: We’re hard at work prepping the YUI 2.x and 3.x code repositories for GitHub deployment as well. We’ll have more to share with you on that front in the near future.

21 Comments

  1. thanks!

    any chance of having it on pypi?

  2. I’ve been using JsDoc Toolkit for a while now to document custom YUI extensions and components. It works well, but after building, I end up with two sets of documentation (YUI docs, and docs for my extensions.) Hopefully this will let us create a cleaner, single set of documentation during our build process.

    Thanks guys!

  3. [...] YUI Doc: A New Tool for Generating JavaScript API Documentation – The Yahoo! User Interface team announce the release of their new Javascript API Documentation tool – think Sandcastle for Javascript. [...]

  4. For corporate developers and IDE (e.g. eclipse) development of large(r) Javascript projects a standard javadoc-like doc format is a must-have.

    Are there any efforts on a larger scale – like the (by now successful) efforts to influence ECMA 4 standardization – to get the industry to agree on one format?

    I would have loved to adopt the jsdoc toolkit, but the more I used it, the more I hated it – it seemed to me the author introduced way too many tags (and without a two-level structure like yuidoc has, with very few main-tags and optional subtags, or at least he doesn’t explain them very well), and also left javadoc-like syntax in the process, introducing different tagnames (and meanings?).

    But the difficulty now is that there is the (it seems) widely visible jsdoc and now yuidoc, with different tags each. That means there is less chance for an IDE developer to develop a JS plugin for eclipse (for example), which uses those comments to (for the first time, right now only rudimentary support exists e.g. in Neatbeans and eclipse plugins) provide meaningful and correct syntax checks and code completion support.

    I think for easier corporate adoption of Javascript directly (vs. writing it indirectly through Java librarys), standardization of the inline doc comment format as well as a good eclipse plugin are both necessary. That would of course overstretch the YUI team – so I’m interested if there are any larger efforts among the big players?

    Privately, my reason for asking is that I’d try to join :-)

  5. [...] Miraglia and our friends at Yahoo! have announced YUI Doc, “a python-based documentation tool that generates API documentation for JavaScript code. YUI [...]

  6. Great, the JsDoc Toolkit has been giving me grief lately, so hopefully this is a better implementation.

    But why couldn’t you have implemented this in Java, like YUICompressor? Now I have to install Python into my build and dev environments as well!

  7. @damien: we will look into getting this published on PyPI.

    @Michael: there is an effort to define a standard for documenting dynamic languages — http://www.scriptdoc.org/ — and Aptana provides Eclipse support for this. Admittedly, we need to look at how well yuidoc syncs with this effort.

    @Adam: yuidoc was created before we had yuicompressor, and building yuicompressor on top of Rhino was the right approach for that tool.

  8. Not to be too nitpicky about it, but… :-)

    One primary tag that can be used when using YUI Doc is “class”. But, as experts on the subject have established, JavaScript is prototype based, not class based. So there are no classes as such in JavaScript, although their behavior is similar.

    Whenever I used @class in my documentation, I was wondering whether this could cause confusion and again make people think that JavaScript is like Java…

  9. @Klaus –

    JavaScript doesn’t have custom events or managed configuration attributes either, and yet we find such constructs useful and create them, and we need to document them when we do. So, in my view, when we leverage the flexibility of JavaScript to do things that are class-like, there’s justification for labeling our construct in a way that conveys its function to the reader.

    Regards,
    Eric

  10. I have primarily been using JsDoc, but I will definitely give this a looking into. The fact that it is written in python, which is language I am very comfortable using, I may be able to add things I would like that may not be in the standard tool.

  11. [...] YUI Doc: A New Tool for Generating JavaScript API Documentation ยป Yahoo! User Interface Blog (tags: yui yahoo javascript documentation) [...]

  12. [...] sfrutta i commenti inseriti nel codice come base per la documentazione finale. Rimandandovi al post di presentazione per ulteriori dettagli, segnalo che un ottimo esempio d’uso di YUI Doc è dato dalla [...]

  13. Hi,

    here’s a fork of yuidoc that can be installed with easy_install:
    http://github.com/dinoboff/yuidoc/tree/master

  14. [...] team now also made YUI Doc – the tool that creates the YUI API Docs available for everybody. It is a python script and allows [...]

  15. Hi

    I have a couple of questions/issues regarding YUI Doc…
    I am a little unclear of the expected relationships between source files, modules and namespaces. Is it expected that there is a 1:1 relationship between source file & module? Would the namespaces used in a module be the exclusive property of that module?

    I have also experimented by defining some submodules, but the result was not as I expected. I would expect the submodules to be displayed in a hierarchy in the navigator, but they were presented in the body of the module page.

    I am in the process of converting from jsdoc toolkit … I miss a few features from this tool, specifically @link to arbitrarily link to a documented artifact from the description.

    There was also an error when I tried to document static members of a constructor (‘@class’). Is this not good?

    Overall I am very impressed. I would have liked navigation based on namespace, as this is the way my existing code is structured … with a moderately long namespace the class references in the navigator overflow the default space allowed. Wouldn’t it be better to have some sort of expandable tree navigation based on distinct namespaces, with just the bare class names as leaves?

  16. @Neil,

    Thanks for the feedback. I’d love to see you post this feedback to the YUI Doc discussion forum –

    http://yuilibrary.com/forum/viewforum.php?f=26

    That would be the best place to have a conversation about the features you’re discussing and the suggestions you’re making for improving the tool.

    Regards,
    Eric

  17. [...] source code. This means it will always be up-to-date even if there are quick fixes in the code. The tool to create the documentation from JavaScript code is also [...]

  18. I wanted to ask ,is it necessary to follow a modular pattern to generate a yuidoc.Since I am newbie to this ,started using this from yesterday only, so i would like to know is it possible to generate a YUI doc without using @class tag.
    For example my js file begins like

    var somevariable=true;

    function foo(a1,a2)
    {
    some code;
    }
    Can please anyone guide me on this ,how to generate a YUI doc without using class tag

  19. Vijetha,

    I’d recommend posting your question on the YUIDoc forum — that’s a better place to get specific questions answered.

    http://yuilibrary.com/forum/viewforum.php?f=26

    -Eric