This document summarizes an upcoming session comparing the YUI Doc and JS Doc Toolkit API documentation generators. The session will discuss how API generators work and their role in documentation. Attendees will learn when to use YUI Doc versus JS Doc Toolkit, and about alternatives to comment-based documentation.

1. API Doc Smackdown
YUI Doc versus JS Doc Toolkit
Monday, September 14, 2009 - 4:30-5:30p

2. API Doc Smackdown
The Yahoo UI (YUI) Library is well known for its excellent documentation. One
of its secrets is YUI Doc, a Python application used at build time to generate
API documentation for JavaScript code.
But is YUI Doc really better than JS Doc Toolkit? -- an elder application, written
in JavaScript, that also generates API documentation. When should you
choose one over the other? Which is the better choice for your project?
In this session you will learn:
* How API generators work, and how documentation helps;
* When to use YUI Doc and when to use JS Doc Toolkit;
* More about alternatives to comment-based documentation.

23. Style Guide
Use <code> style for keywords and name
Use in-line links economically
Omit parentheses for the general form of methods and
constructors
Okay to use phrases instead of complete sentences, in the
interests of brevity.
Use 3rd person (descriptive) not 2nd person (prescriptive)
Method descriptions begin with a verb phrase.
Class/interface/field descriptions can omit the subject and
simply state the object.
Use "this" instead of "the" when referring to an object
created from the current class.
Use "this" instead of "the" when referring to an object
created from the current class.
Avoid Latin.

25. Please complete
an evaluation.

26. Questions?