Download - API Doc Smackdown
API Doc Smackdown
YUI Doc versus JS Doc Toolkit Monday, September 14, 2009 - 2:25-3:25p
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.
Old School
push RA ; push register A to retain the subtotalpop RB ; pop register B to recall the total
Source Code Stakeholders
Solution ArchitectsProduct ManagersQA EngineersMaintenance EngineersCustomers
Why not doc?
Embedded comments clutter up the codeExternal document is difficult to synchronize
http://java.sun.com/j2se/javadoc/writingdoccomments/
http://java.sun.com/j2se/javadoc/writingdoccomments/
http://www.j2ee.me/javase/7/docs/api/index.html?overview-summary.html
Some IDEs with API Doc Support
Eclipse Aptana (ScriptDoc)
Visual Studio Resharper for VSIDEA IntelliJ
Any others?
http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
http://www.birt-exchange.org/documentation/JavaComponents10/JSAPI-JSdoc/
YUI Doc Pros and Cons
ProsConcise set of tagsUsed by YUI library supported by YUI Team
ConsYUI specific idiomsOvershadowed by YUI Small community
http://code.google.com/p/jsdoc-toolkit/wiki/Templates
http://code.google.com/p/jsdoc-toolkit/wiki/Templates
http://code.google.com/p/jsdoc-toolkit/wiki/Templates
D:\opt\Yahoo\yuidoc_1.0.0b1\yuidoc\template\main.tmpl
JsDoc Toolkit Pros and Cons
Pros
Deep and broad tab set Used by many projects Well supported
Cons
Sketchy documentationLacks "anchor" projectSole developer
Time for a Test Drive ...
Installing YUI Doc
Python 2.5C:\Python25
SetupTools $python_home\Scripts\easy_install* (executables)
.> easy_install pygments
.> easy_install simplejson
.> easy_install cheetah
YUI Doc Distributionbin/example.batbin/example.sh
http://www.slideshare.net/ted.husted
http://pypi.python.org/pypi/setuptools
setuptools-0.6c9.win32-py2.5.exe
C:\Python25\Scripts\easy_install
1. easy_install pygments2. easy_install Cheetah3. easy_install simplejson
c:\opt\yahoo\yuidoc_1.0.0b1\yuidoc\bin\example.bat
c:\opt\yahoo\yuidoc_1.0.0b1\yuidoc\bin\example.bat
Installing JsDoc Toolkit
Java 1.5 or 1.6 JsDoc Distribution
appconfjavatemplates
> java -jar jsrun.jar app\run.js -a -t=templates\jsdoc -r app/frame.js app\frame app/handlerout/jsdoc
index.htmlfiles.htmlsymbols\
http://code.google.com/p/jsdoc-toolkit/
YUI Doc vs JsDoc Toolkit
YUI Doc ProsConcise set of tabsUsed by YUI library Supported by YUI Team
Js Doc Pros
Deep and broad tag set Used by many projects Well supported
YUI Doc ConsYUI specific idiomsOvershadowed by YUI Small community
Js Doc Cons
Sketchy documentationLacks "anchor" projectSole developer
Style GuideUse <code> style for keywords and nameUse in-line links economicallyOmit parentheses for the general form of methods and constructorsOkay 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.
http://code.google.com/p/jsdoc-toolkit/
Please complete an evaluation.
