api doc smackdown

Download API Doc Smackdown

Post on 25-May-2015

4.470 views

Category:

Technology

5 download

Embed Size (px)

DESCRIPTION

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?

TRANSCRIPT

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

2. API Doc SmackdownThe 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 Schoolpush RA ; push register A to retain the subtotal pop RB ; pop register B to recall the total 5. Source Code Stakeholders Solution ArchitectsProduct ManagersQA EngineersMaintenance EngineersCustomers 6. Why not doc? Embedded comments clutter up the codeExternal 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 EclipseVisual StudioAptana (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 ConsPros ConsConcise set of tags YUI specific idiomsUsed by YUI library Overshadowed by YUIsupported 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 30. http://code.google.com/p/jsdoc-toolkit/ 31. http://code.google.com/p/jsdoc-toolkit/ 32. http://docs.jproton.com.br/ 33. http://lib.metatype.jp/madtemplate/ 34. http://projects.vinces.ca/jsdocs/ 35. http://code.google.com/p/jsdoc-toolkit/wiki/Templates 36. http://code.google.com/p/jsdoc-toolkit/wiki/Templates 37. http://code.google.com/p/jsdoc-toolkit/wiki/Templates 38. http://developer.yahoo.com/yui/yuidoc/#custom 39. D:optYahooyuidoc_1.0.0b1yuidoctemplatemain.tmpl 40. JsDoc Toolkit Pros and ConsPros ConsDeep and broad tab set Sketchy documentation Used by many projectsLacks "anchor" project Well supported Sole developer 41. Time for a Test Drive ... 42. Installing YUI DocPython 2.5 C:Python25 SetupTools$python_homeScriptseasy_install* (executables).> easy_install pygments.> easy_install simplejson.> easy_install cheetah YUI Doc Distributionbin/example.batbin/example.sh 43. http://python.org/download/releases/2.5.4/ 44. python-2.5.4.msi 45. http://pypi.python.org/pypi/setuptools 46. setuptools-0.6c9.win32-py2.5.exe 47. 1. easy_install pygments 2. easy_install Cheetah 3. easy_install simplejson C:Python25Scriptseasy_install 48. c:optyahooyuidoc_1.0.0b1yuidocbinexample.bat 49. c:optyahooyuidoc_1.0.0b1yuidocbinexample.bat 50. Installing JsDoc Toolkit Java 1.5 or 1.6JsDoc Distribution app conf java templates> java -jar jsrun.jar apprun.js-a -t=templatesjsdoc-r app/frame.js appframe app/handlerout/jsdoc index.html files.html symbolshttp://code.google.com/p/jsdoc-toolkit/ 51. file:///D:/opt/GoogleCode/jsdoc_toolkit-2.3.2/jsdoc-toolkit/out/jsdoc/index. 52. YUI Doc vs JsDoc ToolkitYUI Doc ProsYUI Doc Cons Concise set of tabs YUI specific idioms Used by YUI library Overshadowed by YUI Supported by YUI Team Small communityJs Doc Pros Js Doc Cons Deep and broad tag set Sketchy documentationUsed by many projectsLacks "anchor" projectWell supported Sole developer 53. http://dojodocs.uxebu.com/ 54. http://scriptdoc.org/ 55. Style GuideUse style for keywords and nameUse in-line links economicallyOmit parentheses for the general form of methods andconstructorsOkay to use phrases instead of complete sentences, in theinterests 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 andsimply state the object.Use "this" instead of "the" when referring to an objectcreated from the current class. Use "this" instead of "the" when referring to an objectcreated from the current class.Avoid Latin. http://code.google.com/p/jsdoc-toolkit/ 56. Please completean evaluation. 57. Questions? http://www.slideshare.net/ted.husted