API Doc Smackdown

5,054 views

Published on

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 Comment
1 Like
Statistics
Notes
  • So where is 'When to use YUI Doc and when to use JS Doc Toolkit'?
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
No Downloads
Views
Total views
5,054
On SlideShare
0
From Embeds
0
Number of Embeds
31
Actions
Shares
0
Downloads
24
Comments
1
Likes
1
Embeds 0
No embeds

No notes for slide

API Doc Smackdown

  1. 1. API Doc Smackdown YUI Doc versus JS Doc Toolkit Monday, September 14, 2009 - 2:25-3:25p
  2. 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. 3. http://www.slideshare.net/ted.husted
  4. 4. Old School push RA ; push register A to retain the subtotal pop RB ; pop register B to recall the total
  5. 5. Source Code Stakeholders Solution Architects Product Managers QA Engineers Maintenance Engineers Customers
  6. 6. Why not doc? Embedded comments clutter up the code External document is difficult to synchronize
  7. 7. http://java.sun.com/j2se/javadoc/writingdoccomments/
  8. 8. http://java.sun.com/j2se/javadoc/writingdoccomments/
  9. 9. http://www.j2ee.me/javase/7/docs/api/index.html?overview-summary.html
  10. 10. Some IDEs with API Doc Support Eclipse Visual Studio Aptana (ScriptDoc) Resharper for VS IDEA IntelliJ Any others?
  11. 11. http://ndoc.sourceforge.net/
  12. 12. http://sandcastle.codeplex.com/
  13. 13. http://www.codeplex.com/DocProject
  14. 14. http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
  15. 15. http://www.phpdoc.org/
  16. 16. http://rdoc.rubyforge.org/
  17. 17. http://www.birt-exchange.org/documentation/JavaComponents10/JSAPI-JSdoc/
  18. 18. http://developer.yahoo.com/yui/docs/
  19. 19. http://developer.yahoo.com/yui/yuidoc/
  20. 20. http://developer.yahoo.com/yui/yuidoc/
  21. 21. http://developer.yahoo.com/yui/yuidoc/
  22. 22. http://developer.yahoo.com/yui/yuidoc/
  23. 23. http://developer.yahoo.com/yui/yuidoc/
  24. 24. http://developer.yahoo.com/yui/yuidoc/
  25. 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. 26. http://developer.yahoo.com/yui/yuidoc/
  27. 27. http://code.google.com/p/jsdoc-toolkit/
  28. 28. http://code.google.com/p/jsdoc-toolkit/w/list
  29. 29. http://code.google.com/p/jsdoc-toolkit/w/list
  30. 30. http://code.google.com/p/jsdoc-toolkit/
  31. 31. http://code.google.com/p/jsdoc-toolkit/
  32. 32. http://docs.jproton.com.br/
  33. 33. http://lib.metatype.jp/madtemplate/
  34. 34. http://projects.vinces.ca/jsdocs/
  35. 35. http://code.google.com/p/jsdoc-toolkit/wiki/Templates
  36. 36. http://code.google.com/p/jsdoc-toolkit/wiki/Templates
  37. 37. http://code.google.com/p/jsdoc-toolkit/wiki/Templates
  38. 38. http://developer.yahoo.com/yui/yuidoc/#custom
  39. 39. D:optYahooyuidoc_1.0.0b1yuidoctemplatemain.tmpl
  40. 40. 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
  41. 41. Time for a Test Drive ...
  42. 42. 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
  43. 43. http://python.org/download/releases/2.5.4/
  44. 44. python-2.5.4.msi
  45. 45. http://pypi.python.org/pypi/setuptools
  46. 46. setuptools-0.6c9.win32-py2.5.exe
  47. 47. 1. easy_install pygments 2. easy_install Cheetah 3. easy_install simplejson C:Python25Scriptseasy_install
  48. 48. c:optyahooyuidoc_1.0.0b1yuidocbinexample.bat
  49. 49. c:optyahooyuidoc_1.0.0b1yuidocbinexample.bat
  50. 50. 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/
  51. 51. file:///D:/opt/GoogleCode/jsdoc_toolkit-2.3.2/jsdoc-toolkit/out/jsdoc/index.
  52. 52. 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
  53. 53. http://dojodocs.uxebu.com/
  54. 54. http://scriptdoc.org/
  55. 55. 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/
  56. 56. Please complete an evaluation.
  57. 57. Questions? http://www.slideshare.net/ted.husted

×