Beautiful Documentation with YUI Doc

Creating Beautiful Documentation with YUI Doc Stephen Woods YUICONF 2009

/** * Frontend Engineer in Yahoo! Internal * Platform group. I write apis all day * * @module YUI Doc * @author Stephen Woods */ YUICONF 2009

I hate writing Documentation YUICONF 2009

I hate writing Documentation Undocumented code is worse. YUICONF 2009

But.myCodeIsSelfDocumenting(); //and well commented YUICONF 2009

If you are writing APIs good documentation is a requirement YUICONF 2009

True Stories of Bad Documentation YUICONF 2009

WRITING DOCS YUICONF 2009

YUICONF 2009

How do they make those wonderful Docs? YUICONF 2009

YUICONF 2009

Write Code Start to Docs Change Code Tell People to Explain Why the Fix Bugs Read the Docs Docs are Wrong Realize you forgot to Start to ﬁx Docs Fix More Bugs Update the docs YUICONF 2009

YUICONF 2009

Write Code YUICONF 2009

Write Code Have Docs YUICONF 2009

Write Code (MAGIC) Have Docs YUICONF 2009

(MAGIC) YUICONF 2009

YUICONF 2009

CppDoc Doxygen JavaDoc PhpDocumentor JSDoc YUI Doc YARD YUICONF 2009

CppDoc Doxygen JavaDocDoc Generators PhpDocumentor Better Living JSDoc Through Automation YUI Doc YARD YUICONF 2009

Doc Generators Automatically create documentation from code js YUICONF 2009

What is YUI Doc? /** * Encodes the string as an LZW * compressed binary stream * * @method encode * @static * @param {String} str The string to encode * @return {String} The encoded string */ encode:function(str){ YUICONF 2009

What is YUI Doc? YUICONF 2009

YUI Doc YUICONF 2009

YUI Doc A language-neutral way to automagically generate beautiful documentation YUICONF 2009

language-neutral YUICONF 2009

using System; /** * C# Module Description * @module lang.csharp */ /** * C# Class Description * @class ReadAll C# * @namespace PlayingAround */ namespace PlayingAround { class ReadAll { /** * Main Method * @method Main * @static */ public static void Main(string[] args) { string contents = System.IO.File.ReadAllText(@"C:t1"); Console.Out.WriteLine("contents = " + contents); } } } YUICONF 2009

/** * Test Java Module Description * @module lang.javatest */ import java.util.*; /** * This is the class description for this Java Class * @class Test * @namespace Java Java * @constructor */ public class Test { /** * x property * @property x * @type {Double} */ private double x; /** * y property * @property y * @type {Double} */ private double y; } YUICONF 2009

#!/usr/bin/env python ''' /** * Test Python File * @module testpy */ ''' import os, sys, string, shutil, urllib2, urllib, pprint, simplejson, datetime from cStringIO import StringIO from subprocess import call, PIPE, Popen Python ''' /** * This is a test class * @class TestPy * @namespace Python */ ''' ''' /** * Test Method * @method test */ ''' def test(): pass YUICONF 2009

=begin /** * Module Info for test Ruby File * @module lang.rubytest */ =end require 'rubygems' require 'grit' require 'optparse' require 'logger' require 'fileutils' Ruby module RubyTest =begin /** * Class Information * @class test * @namespace Ruby */ =end class Test =begin /** * Execute desc * @method execute */ =end def self.execute #foo end YUICONF 2009

/** * This method syncs the value of time object, * including building the strings for 12hr and 24hr * also fires a 'timechange' event * @method _syncTime * @protected * */ _syncTime:function(){ JavaScript var time = this.get('time'), ampm = time.ampm, strings = this.get('strings'), seperator = this.get('strings.seperator'), minute = pad(time.minute); //build the string for ampm based on the strings ampmString = (ampm == AM) ? this.get(AMSTR_KEY) : this.get(PMSTR_KEY); //store the string representation of the 12 hour time this.set('time.s12hour', ((time.hour == 0) ? 12 : time.hour) + seperator + minute + ampmString); YUICONF 2009

language-neutral ‣ Primarily generated from special comment blocks YUICONF 2009

language-neutral ‣ Primarily generated from special comment blocks ‣ Can work with any language YUICONF 2009

language-neutral ‣ Primarily generated from special comment blocks ‣ Can work with any language ‣ Lets you describe code however makes sense YUICONF 2009

language-neutral ‣ Will fall out of sync YUICONF 2009

language-neutral ‣ Will fall out of sync ‣ There will be copy/paste errors YUICONF 2009

language-neutral ‣ Will fall out of sync ‣ There will be copy/paste errors ‣ Type mismatches will happen YUICONF 2009

YUI Doc A language-neutral way to automagically generate Beautiful Documentation YUICONF 2009

Beautiful Documentation YUICONF 2009

Beautiful Documentation ‣ Accurate YUICONF 2009

Beautiful Documentation ‣ Accurate ‣ Complete YUICONF 2009

Beautiful Documentation ‣ Accurate ‣ Complete ‣ Useable YUICONF 2009

Beautiful Documentation ‣ Accurate ‣ Complete ‣ Useable ‣ Understandable YUICONF 2009

USING YUI DOC YUICONF 2009

Sample Project My Project compression lzw.js lzw-lite.js widgets timepickerwidget.js http://bit.ly/samplebuild YUICONF 2009

Project Structure YUICONF 2009

Project Structure Project Module Module ~/LZW ~/Timepicker Class Class Class LZW LZW-Lite Timepicker YUICONF 2009

Comment Blocks YUICONF 2009

Comment Blocks /** * Description * @tag tagValue * @secondaryTag secondaryValue */ YUICONF 2009

Primary Tags ‣ @module ‣ @class ‣ @property ‣ @event ‣ @method YUICONF 2009

Secondary Tags ‣ @submodule ‣ @extends ‣ @namespace ‣ @conﬁg *YUI Speciﬁc YUICONF 2009

@param & @return Datatypes! @param {type} name description @return {type} description YUICONF 2009

Object {} Array String @param Boolean Name Description Number Mixed MyType YUICONF 2009

@module YUICONF 2009

@module /** * A javascript file compression library * @module Compression * @requires node, event */ /** * Provides LZW compression * @module Compression * @submodule Compression-LZW */ YUICONF 2009

@module YUICONF 2009

@class /** * A YUI timepicker widget * * @class Timepicker * @constructor * @namespace Y.Saw * @extends Widget */ YUI.add('timepicker', function(Y){ YUICONF 2009

@class YUICONF 2009

@event /** * Fires when a new day begins * * @event dawn * @param {String} color * @param {Number} duration */ YUICONF 2009

@event YUICONF 2009

@property /** * Symbol for AM * @property AM * @type String */ YUICONF 2009

@property YUICONF 2009

@property + @attribute /** * @property Timepicker.ATTRS * @type Object * @protected * @static */ Timepicker.ATTRS = { /** * The selected time * @attribute time * @type Object * @default {hour:0, minute:0, ampm:'AM'} */ YUICONF 2009

@property + @attribute YUICONF 2009

@method /** * Utility method that returns the size * of a unicode string in bytes * @method strSize * @param {String}str The string to evaluate * @return {Number} the length of the * string in bytes */ strSize:function(str){ YUICONF 2009

@method YUICONF 2009

BUILDING DOCS YUICONF 2009

http://bit.ly/yuidoc YUICONF 2009

YUICONF 2009

> yuidoc.py myLib -p doctmp/parsertmp -o doctmp/tocs -t template -m 'YUI Doc Demo' -Y "3.0.0b1" -v "0.0.1" YUICONF 2009

example.sh parser_in="$HOME/src" parser_out=~/www/docs/parser generator_out=~/www/docs/generator template=$yuidoc_home/template YUICONF 2009

yourbuild.sh parser_in="$HOME/src" parser_out=~/www/docs/parser generator_out=~/www/docs/generator template=yourtemplate projectname='YUI Doc Demo' version='1.0.0' yuiversion='3.0.0' url='http://your.project.url -t $template -m $projectname -Y $yuiversion -v $version -u $url YUICONF 2009

Slide Title Slide Content <target name="doc"> <mkdir dir="${tmp_dir}" /> <mkdir dir="${tmp_dir}/parsertmp" /> <property name="parser_out" location="${tmp_dir}/parsertmp" /> <property name="generator_out" location="${doc_dir}" /> <property name="template" location="template" /> <property name="yuiversion" location="3.0.0" /> <echo>generating documentation</echo> <exec executable="${yuidoc_exec}"> <arg value="${parser_in}"/> <arg value="-p"/> <arg value="${parser_out}"/> <arg value="-o" /> <arg value="${generator_out}" /> <arg value="-t" /> <arg value="${template}" /> YUICONF 2009

Watch out for: YUICONF 2009

.git Watch out for: .cvs .svn YUICONF 2009

KEEPING DOCS RELEVANT YUICONF 2009

Simple Rules YUICONF 2009

Simple Rules ‣ Generate documentation as part of the build YUICONF 2009

Simple Rules ‣ Generate documentation as part of the build ‣ Don't manually check documentation in to VCS YUICONF 2009

Simple Rules ‣ Generate documentation as part of the build ‣ Don't manually check documentation in to VCS ‣ Treat documentation comments like code YUICONF 2009

‣ Treat documentation comments like code YUICONF 2009

‣ Treat documentation comments like code ‣ Include as part of reviews YUICONF 2009

‣ Treat documentation comments like code ‣ Includeas part of reviews ‣ Comments are source, docs are compiled code YUICONF 2009

‣ Treat documentation comments like code ‣ Include as part of reviews ‣ Comments are source, docs are compiled code ‣ File documentation bugs if docs and code are out of sync. YUICONF 2009

TRY IT OUT YUICONF 2009

git://github.com/saw/YUI-Doc-Example.git YUICONF 2009

./build.sh ant build YUICONF 2009

./build.sh ant build #!/bin/sh #first do the build (just copying files) mkdir build; cp -r myLib/* build/; # The location of your yuidoc install yuidoc_home=/Applications/yuidoc; mkdir -p doctmp/{parsertmp,docs}; mkdir myDocs; # The location of the files to parse. Parses subdirectories, parser_in="myLib"; parser_out=doctmp/parsertmp; # The directory to put the html file outputted by the generator generator_out=doctmp/docs; template=template projectname='YUI Doc Demo' version="0.0.1" yuiversion="3.0.0" $yuidoc_home/bin/yuidoc.py $parser_in -p $parser_out -o $generator_out -t $template -m 'YUI Doc Demo' -Y YUICONF 2009

./build.sh ant build #!/bin/sh <?xml version="1.0"?> #first do the build (just copying files) mkdir build; <project name="SawLib"> cp -r myLib/* build/; <property name="build_dir" location="build" / > # The location of your yuidoc install <property name="src" location="myLib" /> yuidoc_home=/Applications/yuidoc; <property name="projectname" value="YUI Doc Demo" /> mkdir -p doctmp/{parsertmp,docs}; <property name="version" value="1.0" /> mkdir myDocs; <property name="project_url" value="http:// developer.yahoo.com/yui/yuidoc" /> # The location of the files to parse. Parses <property name="doc_dir" location="myDocs" /> subdirectories, <property name="yuidoc_home" location="/ parser_in="myLib"; Applications/yuidoc" /> <property name="yuidoc_exec" location="$ parser_out=doctmp/parsertmp; {yuidoc_home}/bin/yuidoc.py" /> <property name="tmp_dir" location="doctmp" /> # The directory to put the html file outputted by the <property name="parser_in" location="myLib" / generator > generator_out=doctmp/docs; <target name="init"> template=template <echo>Making sure build dir is there</ projectname='YUI Doc Demo' echo> version="0.0.1" <mkdir dir="${build_dir}" /> yuiversion="3.0.0" </target> $yuidoc_home/bin/yuidoc.py $parser_in -p $parser_out -o $generator_out -t $template -m 'YUI Doc Demo' -Y YUICONF 2009

ant build YUICONF 2009

CUSTOM TEMPLATES YUICONF 2009

Edit the stylesheet: templates/assets/api.css YUICONF 2009

Create a Custom Template template/main.tmpl YUI Doc Demo Modules • Compression Files • widget • lzw-lite.js Classes • lzw.js • saw.lzw • timepickerwidget.js • saw.lzw-binary Methods Class saw.lzw Implements the LZW compression algoritm, outputting binary using the Unicode character equivilant of the decimal codes Methods cheetahtemplate.org encode static String encode ( str ) Encodes the string as an LZW compressed binary stream...except because we can't really use binary in javascript we are using the unicode character speciﬁed by the decimal code output by the algorithm in each place Parameters: str <String> The string to encode Returns: String str The encoded string YUICONF 2009

CUSTOM EVERYTHING YUICONF 2009

Parser can be used for any Front end http://bit.ly/airdoc YUICONF 2009

The YUI Doc Parser Works Alone parser_in="$HOME/src" parser_out= ~/www/docs/parser generator_out=~/www/docs/generator template=$yuidoc_home/template YUICONF 2009

} }, The YUI Doc Parser Works Alone "file": "lzw.js", "shortname": "lzw", "description": "Implements the LZW compression algoritm, outputting nbinary using the Unicode character equivilant of thendecimal codes" ~/www/docs/parser/parsed.json }, } "version": "0.0.1", "namespaces": ["saw", "Y.Saw"] } YUICONF 2009

The YUI Doc Parser Works Alone ~/www/docs/parser/parsed.json Complete JSON Representation of Documentation { "majorversion": 3, "filemap": { "lzw-lite.js": { "classlist": ["saw.lzw-binary"], "name": "lzw-lite.js", "module": "Compression" }, "lzw.js": { "classlist": ["saw.lzw"], "name": "lzw.js", "module": "Compression" }, "timepickerwidget.js": { "classlist": ["Y.Saw.Timepicker"], "name": "timepickerwidget.js", "module": "Compression" } }, "modules": { "widget": { "description": "Great widgets from saw", "submodules": [], "classlist": ["Y.Saw.Timepicker"], "filelist": [], "subdata": {}, "requires": "oop, event-custom, attribute, base, dom, classnamemanager, widget, event", "name": "widget" }, "Compression": { "name": "Compression", "submodules": ["lzw-binary"], YUICONF 2009 "classlist": ["saw.lzw-binary", "saw.lzw"], "filelist": ["lzw-lite.js", "lzw.js", "timepickerwidget.js"], "subdata": {

And Code Highlighting too! ~/www/docs/parser /lzw.js.highlighted (function(){ var STARTPOINT = 256; //create "saw" global if not there if(window.saw === undefined){ window.saw = {}; } /** * Returns a pre-popuated dictionary to begin encoding * @private * @method getDic * @return {Object} a hash table with ascii letters as keys */ function getDic(){ var result = {}; for (var i=0; i < STARTPOINT; i++) { var ch = String.fromCharCode(i); result[ch] = i; YUICONF 2009

Parting Tips YUICONF 2009

Parting Tips ‣ Documentation is part of the build YUICONF 2009

Parting Tips ‣ Documentation is part of the build ‣ Use ant/phing/whatever tasks to run docs YUICONF 2009

Parting Tips ‣ Documentation is part of the build ‣ Use ant/phing/whatever tasks to run docs ‣ Use a documentation server YUICONF 2009

Stephen Woods @ysaw Y!IM: stephenwoods_corp YUICONF 2009

http://www.slideshare.net	46
http://www.jiamaocode.com	41
http://www.jm47.com	14
http://www.techgig.com	8
http://dev.topming.com	7

Beautiful Documentation with YUI Doc

by Stephen Woods

Accessibility

Categories

Upload Details

Usage Rights

5 Embeds 116

Statistics

Beautiful Documentation with YUI Doc Presentation Transcript