API Doc Smackdown

38 %
62 %
Information about API Doc Smackdown
Technology

Published on September 8, 2009

Author: ted.husted

Source: slideshare.net

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?

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.

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

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

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

Why not doc? Embedded comments clutter up the code External 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 Visual Studio Aptana (ScriptDoc) Resharper for VS IDEA IntelliJ Any others?

http://ndoc.sourceforge.net/

http://sandcastle.codeplex.com/

http://www.codeplex.com/DocProject

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

http://www.phpdoc.org/

http://rdoc.rubyforge.org/

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

D:optYahooyuidoc_1.0.0b1yuidoctemplatemain.tmpl

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

Time for a Test Drive ...

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

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

python-2.5.4.msi

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

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

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

c:optyahooyuidoc_1.0.0b1yuidocbinexample.bat

c:optyahooyuidoc_1.0.0b1yuidocbinexample.bat

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/

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

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

http://dojodocs.uxebu.com/

http://scriptdoc.org/

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/

Please complete an evaluation.

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

Add a comment

Related presentations

Presentación que realice en el Evento Nacional de Gobierno Abierto, realizado los ...

In this presentation we will describe our experience developing with a highly dyna...

Presentation to the LITA Forum 7th November 2014 Albuquerque, NM

Un recorrido por los cambios que nos generará el wearabletech en el futuro

Um paralelo entre as novidades & mercado em Wearable Computing e Tecnologias Assis...

Microsoft finally joins the smartwatch and fitness tracker game by introducing the...

Related pages

API Doc Smackdown - Technology - documents.mx

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 ...
Read more

Api Doc | LinkedIn

View 110 Api Doc posts, presentations, experts, and more. Get the professional knowledge you need on LinkedIn.
Read more

Unmanaged API Doc - Documents

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 ...
Read more

The Ajax Experience - Boston - JavaScript Sessions

Understand how to use JavaScript, ... API Doc Smackdown: YUI Doc versus JS Doc Toolkit with Ted Husted ; ... the web browser API so crucial to your work;
Read more

The Ajax Experience - Boston - Frameworks Sessions

The Ajaxian Framework Summit features the three most popular open source Ajax frameworks holding ... API Doc Smackdown: YUI Doc versus JS Doc ...
Read more

Docs skel · gar1t/pyerl-concurrency-smackdown@67c7bd6

@@ -0,0 +1,216 @@ + # -*- coding: utf-8 -*-+ # + # Python Erlang Concurrency Smackdown documentation build configuration file, created by + # sphinx ...
Read more

Google Drive - Cloud Storage & File Backup for Photos ...

Get access to files anywhere through secure cloud storage and file backup for your photos, videos, files and more with Google Drive.
Read more

YouTube for Developers - YouTube

Whether you’re building a business on YouTube or want to enhance your app with video, a rich set of YouTube APIs can bring your products to life
Read more