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?

1. API Doc Smackdown
YUI Doc versus JS Doc Toolkit
Monday, September 14, 2009 - 2:25-3:25p

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.

3. http://www.slideshare.net/ted.husted

4. Old School
push RA ; push register A to retain the subtotal
pop RB ; pop register B to recall the total

5. Source Code Stakeholders
Solution Architects
Product Managers
QA Engineers
Maintenance Engineers
Customers

6. Why not doc?
Embedded comments clutter up the code
External document is difficult to synchronize

7. http://java.sun.com/j2se/javadoc/writingdoccomments/

8. http://java.sun.com/j2se/javadoc/writingdoccomments/

9. http://www.j2ee.me/javase/7/docs/api/index.html?overview-summary.html

10. Some IDEs with API Doc Support
Eclipse Visual Studio
Aptana (ScriptDoc) Resharper for VS
IDEA IntelliJ
Any others?

11. http://ndoc.sourceforge.net/

12. http://sandcastle.codeplex.com/

13. http://www.codeplex.com/DocProject

14. http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

15. http://www.phpdoc.org/

16. http://rdoc.rubyforge.org/

17. http://www.birt-exchange.org/documentation/JavaComponents10/JSAPI-JSdoc/

18. http://developer.yahoo.com/yui/docs/

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

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

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

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

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

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

25. YUI Doc Pros and Cons
Pros Cons
Concise set of tags YUI specific idioms
Used by YUI library Overshadowed by YUI
supported by YUI Team Small community

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

27. http://code.google.com/p/jsdoc-toolkit/

28. http://code.google.com/p/jsdoc-toolkit/w/list

29. http://code.google.com/p/jsdoc-toolkit/w/list

31. http://code.google.com/p/jsdoc-toolkit/

32. http://code.google.com/p/jsdoc-toolkit/

34. http://docs.jproton.com.br/

35. http://lib.metatype.jp/madtemplate/

36. http://projects.vinces.ca/jsdocs/

37. http://code.google.com/p/jsdoc-toolkit/wiki/Templates

38. http://code.google.com/p/jsdoc-toolkit/wiki/Templates

39. http://code.google.com/p/jsdoc-toolkit/wiki/Templates

40. http://developer.yahoo.com/yui/yuidoc/#custom

41. D:optYahooyuidoc_1.0.0b1yuidoctemplatemain.tmpl

42. JsDoc Toolkit Pros and Cons
Pros Cons
Deep and broad tab set Sketchy documentation
Used by many projects Lacks "anchor" project
Well supported Sole developer

43. Time for a Test Drive ...

44. Installing YUI Doc
Python 2.5
C:Python25
SetupTools
$python_homeScriptseasy_install* (executables)
.> easy_install pygments
.> easy_install simplejson
.> easy_install cheetah
YUI Doc Distribution
bin/example.bat
bin/example.sh

45. http://python.org/download/releases/2.5.4/

46. python-2.5.4.msi

47. http://pypi.python.org/pypi/setuptools

48. setuptools-0.6c9.win32-py2.5.exe

49. 1. easy_install pygments
2. easy_install Cheetah
3. easy_install simplejson
C:Python25Scriptseasy_install

50. c:optyahooyuidoc_1.0.0b1yuidocbinexample.bat

51. c:optyahooyuidoc_1.0.0b1yuidocbinexample.bat

53. Installing JsDoc Toolkit
Java 1.5 or 1.6
JsDoc Distribution
app
conf
java
templates
> java -jar jsrun.jar apprun.js
-a -t=templatesjsdoc
-r app/frame.js appframe app/handler
out/jsdoc
index.html
files.html
symbols
http://code.google.com/p/jsdoc-toolkit/

54. file:///D:/opt/GoogleCode/jsdoc_toolkit-2.3.2/jsdoc-toolkit/out/jsdoc/index.

55. YUI Doc vs JsDoc Toolkit
YUI Doc Pros YUI Doc Cons
Concise set of tabs YUI specific idioms
Used by YUI library Overshadowed by YUI
Supported by YUI Team Small community
Js Doc Pros Js Doc Cons
Deep and broad tag set Sketchy documentation
Used by many projects Lacks "anchor" project
Well supported Sole developer

56. http://dojodocs.uxebu.com/

57. http://scriptdoc.org/

58. 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.
http://code.google.com/p/jsdoc-toolkit/

59. Please complete
an evaluation.

60. Questions?
http://www.slideshare.net/ted.husted