17. 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 fix Docs Fix More Bugs
Update the docs
YUICONF 2009
34. /**
* 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
35. #!/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
36. =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
37. /**
* 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
39. language-neutral
‣ Primarily generated from special comment blocks
YUICONF 2009
40. language-neutral
‣ Primarily generated from special comment blocks
‣ Can work with any language
YUICONF 2009
41. language-neutral
‣ Primarily generated from special comment blocks
‣ Can work with any language
‣ Lets you describe code however makes sense
YUICONF 2009
73. @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
86. Simple Rules
‣ Generate documentation as
part of the build
YUICONF 2009
87. Simple Rules
‣ Generate documentation as
part of the build
‣ Don't manually check
documentation in to VCS
YUICONF 2009
88. Simple Rules
‣ Generate documentation as
part of the build
‣ Don't manually check
documentation in to VCS
‣ Treat documentation
comments like code
YUICONF 2009
91. ‣ Treat documentation comments
like code
‣ Includeas part of reviews
‣ Comments are source, docs
are compiled code
YUICONF 2009
92. ‣ 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
96. ./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
97. ./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
101. 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 specified 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
108. 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
110. Parting Tips
‣ Documentation is part of the build
YUICONF 2009
111. Parting Tips
‣ Documentation is part of the build
‣ Use ant/phing/whatever tasks to run docs
YUICONF 2009
112. Parting Tips
‣ Documentation is part of the build
‣ Use ant/phing/whatever tasks to run docs
‣ Use a documentation server
YUICONF 2009
113. Stephen Woods
@ysaw
Y!IM: stephenwoods_corp
YUICONF 2009
Hinweis der Redaktion
This talk is for anyone that writes apis other developers need to rely on
YOU might be that other developer
there is a lot to cover, this is an overview, check the website for examples
most people do
but I hate undocumented code!
most people do
That's fine if is regular code
but if its an api..
No one will read your code
if you provide an api, thats the point of an api
These are from real im conversations I found in my archive
If "goodness" doesn't work
why not self preservation?
Good docs save you time
These are from real im conversations I found in my archive
If "goodness" doesn't work
why not self preservation?
Good docs save you time
These are from real im conversations I found in my archive
If "goodness" doesn't work
why not self preservation?
Good docs save you time
These are from real im conversations I found in my archive
If "goodness" doesn't work
why not self preservation?
Good docs save you time
These are from real im conversations I found in my archive
If "goodness" doesn't work
why not self preservation?
Good docs save you time
These are from real im conversations I found in my archive
If "goodness" doesn't work
why not self preservation?
Good docs save you time
These are from real im conversations I found in my archive
If "goodness" doesn't work
why not self preservation?
Good docs save you time
These are from real im conversations I found in my archive
If "goodness" doesn't work
why not self preservation?
Good docs save you time
These are from real im conversations I found in my archive
If "goodness" doesn't work
why not self preservation?
Good docs save you time
Almost every api you encounter has amazingly
complete api documentation. Like Ruby on Rails
Almost every api you encounter has amazingly
complete api documentation. Like Ruby on Rails
Like windows
and of course YUI
How do they do that?
Documentation writing usually goes something like this
People try all types of solutions to this issue, policy, templates, rules
Documentation writing usually goes something like this
People try all types of solutions to this issue, policy, templates, rules
Documentation writing usually goes something like this
People try all types of solutions to this issue, policy, templates, rules
Documentation writing usually goes something like this
People try all types of solutions to this issue, policy, templates, rules
Documentation writing usually goes something like this
People try all types of solutions to this issue, policy, templates, rules
Documentation writing usually goes something like this
People try all types of solutions to this issue, policy, templates, rules
Documentation writing usually goes something like this
People try all types of solutions to this issue, policy, templates, rules
Documentation writing usually goes something like this
People try all types of solutions to this issue, policy, templates, rules
Documentation writing usually goes something like this
People try all types of solutions to this issue, policy, templates, rules
But Ideally the process goes like this
But Ideally the process goes like this
But Ideally the process goes like this
But Ideally the process goes like this
but the only way to make sure that you have docs is to automate it
but the only way to make sure that you have docs is to automate it
but the only way to make sure that you have docs is to automate it
but the only way to make sure that you have docs is to automate it
There are varying degrees of smartness
Some really read the code (doxygen, phpdocumentor) and will kind of work
with no comments
YUI doesn't read the code
takes comment blocks
turns it into pretty documentation
YUI doesn't read the code
takes comment blocks
turns it into pretty documentation
language neutral, generated (mostly) from comment blocks
works with any language
lets you describe the code however makes sense...in other words supports all those strange
idioms in javascript
language neutral, generated (mostly) from comment blocks
works with any language
lets you describe the code however makes sense...in other words supports all those strange
idioms in javascript
language neutral, generated (mostly) from comment blocks
works with any language
lets you describe the code however makes sense...in other words supports all those strange
idioms in javascript
Downsides
Downsides
Downsides
Beautiful documentation is like beautiful code, it is efficient and elegant.
Its most important traits accuracy, docs should match the api
complete: no one likes an undocumented feature
useable: users are developers, if they can't find the docs, they might as well not exist
understandable: the docs should actually make sense. Sadly this can't be automated
Beautiful documentation is like beautiful code, it is efficient and elegant.
Its most important traits accuracy, docs should match the api
complete: no one likes an undocumented feature
useable: users are developers, if they can't find the docs, they might as well not exist
understandable: the docs should actually make sense. Sadly this can't be automated
Beautiful documentation is like beautiful code, it is efficient and elegant.
Its most important traits accuracy, docs should match the api
complete: no one likes an undocumented feature
useable: users are developers, if they can't find the docs, they might as well not exist
understandable: the docs should actually make sense. Sadly this can't be automated
Beautiful documentation is like beautiful code, it is efficient and elegant.
Its most important traits accuracy, docs should match the api
complete: no one likes an undocumented feature
useable: users are developers, if they can't find the docs, they might as well not exist
understandable: the docs should actually make sense. Sadly this can't be automated
Comments describe whats going on
each block can have ONLY one tag
and as many secondaryTags as you like
I'm only going to talk about @return and @param, but there is a lot of flexibility here
These are data types for javascript, anything you want will work of course
but consistency is a good policy
module is a submodule of a parent module.
YUI 3.x anim-scroll is a submodule of anim.
A submodule encompasses a subset of the parent module's functionality.
module is a submodule of a parent module.
YUI 3.x anim-scroll is a submodule of anim.
A submodule encompasses a subset of the parent module's functionality.
Basic unit of functionality, generally its a javascript object
module is a submodule of a parent module.
YUI 3.x anim-scroll is a submodule of anim.
A submodule encompasses a subset of the parent module's functionality.
Events are fundemental to js, and need documenting, remember events don't necessarily get defined, just fired. I tend to create parts of a file, or a whole seperate file that contains events
this is what we are documenting
this is what we are documenting
this is what we are documenting
this is what we are documenting
Attribute is really only applicable if you are using the attribute provider
or YUI 3 attribute, like in widget
Method docs are the meat of api docs
these must be complete and good
data types are really important
Lots of command line options here
don't stress, write a build script!
if you are confused try -h
A simple build script
just an example
your project won't work
A simple build script
just an example
your project won't work