Search

Beautiful Documentation with YUI Doc

Loading...

Flash Player 9 (or above) is needed to view presentations.
We have detected that you do not have it on your computer. To install it, go here.

0 comments

Post a comment

    Post a comment
    Embed Video
    Edit your comment Cancel

    Notes on slide 1

    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

    5 Favorites

    Beautiful Documentation with YUI Doc - Presentation Transcript

    1. Creating Beautiful Documentation with YUI Doc Stephen Woods YUICONF 2009
    2. /** * Frontend Engineer in Yahoo! Internal * Platform group. I write apis all day * * @module YUI Doc * @author Stephen Woods */ YUICONF 2009
    3. I hate writing Documentation YUICONF 2009
    4. I hate writing Documentation Undocumented code is worse. YUICONF 2009
    5. But.myCodeIsSelfDocumenting(); //and well commented YUICONF 2009
    6. If you are writing APIs good documentation is a requirement YUICONF 2009
    7. True Stories of Bad Documentation YUICONF 2009
    8. True Stories of Bad Documentation YUICONF 2009
    9. True Stories of Bad Documentation YUICONF 2009
    10. WRITING DOCS YUICONF 2009
    11. YUICONF 2009
    12. How do they make those wonderful Docs? YUICONF 2009
    13. How do they make those wonderful Docs? YUICONF 2009
    14. How do they make those wonderful Docs? YUICONF 2009
    15. How do they make those wonderful Docs? YUICONF 2009
    16. YUICONF 2009
    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
    18. YUICONF 2009
    19. Write Code YUICONF 2009
    20. Write Code Have Docs YUICONF 2009
    21. Write Code (MAGIC) Have Docs YUICONF 2009
    22. (MAGIC) YUICONF 2009
    23. (MAGIC) YUICONF 2009
    24. YUICONF 2009
    25. CppDoc Doxygen JavaDoc PhpDocumentor JSDoc YUI Doc YARD YUICONF 2009
    26. CppDoc Doxygen JavaDocDoc Generators PhpDocumentor Better Living JSDoc Through Automation YUI Doc YARD YUICONF 2009
    27. Doc Generators Automatically create documentation from code js YUICONF 2009
    28. 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
    29. What is YUI Doc? YUICONF 2009
    30. YUI Doc YUICONF 2009
    31. YUI Doc A language-neutral way to automagically generate beautiful documentation YUICONF 2009
    32. language-neutral YUICONF 2009
    33. 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
    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
    38. language-neutral 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
    42. language-neutral YUICONF 2009
    43. language-neutral ‣ Will fall out of sync YUICONF 2009
    44. language-neutral ‣ Will fall out of sync ‣ There will be copy/paste errors YUICONF 2009
    45. language-neutral ‣ Will fall out of sync ‣ There will be copy/paste errors ‣ Type mismatches will happen YUICONF 2009
    46. YUI Doc A language-neutral way to automagically generate Beautiful Documentation YUICONF 2009
    47. Beautiful Documentation YUICONF 2009
    48. Beautiful Documentation ‣ Accurate YUICONF 2009
    49. Beautiful Documentation ‣ Accurate ‣ Complete YUICONF 2009
    50. Beautiful Documentation ‣ Accurate ‣ Complete ‣ Useable YUICONF 2009
    51. Beautiful Documentation ‣ Accurate ‣ Complete ‣ Useable ‣ Understandable YUICONF 2009
    52. USING YUI DOC YUICONF 2009
    53. Sample Project My Project compression lzw.js lzw-lite.js widgets timepickerwidget.js http://bit.ly/samplebuild YUICONF 2009
    54. Project Structure YUICONF 2009
    55. Project Structure Project Module Module ~/LZW ~/Timepicker Class Class Class LZW LZW-Lite Timepicker YUICONF 2009
    56. Comment Blocks YUICONF 2009
    57. Comment Blocks /** * Description * @tag tagValue * @secondaryTag secondaryValue */ YUICONF 2009
    58. Primary Tags ‣ @module ‣ @class ‣ @property ‣ @event ‣ @method YUICONF 2009
    59. Secondary Tags ‣ @submodule ‣ @extends ‣ @namespace ‣ @config *YUI Specific YUICONF 2009
    60. @param & @return Datatypes! @param {type} name description @return {type} description YUICONF 2009
    61. Object {} Array String @param Boolean Name Description Number Mixed MyType YUICONF 2009
    62. @module YUICONF 2009
    63. @module /** * A javascript file compression library * @module Compression * @requires node, event */ /** * Provides LZW compression * @module Compression * @submodule Compression-LZW */ YUICONF 2009
    64. @module YUICONF 2009
    65. @class /** * A YUI timepicker widget * * @class Timepicker * @constructor * @namespace Y.Saw * @extends Widget */ YUI.add('timepicker', function(Y){ YUICONF 2009
    66. @class YUICONF 2009
    67. @event /** * Fires when a new day begins * * @event dawn * @param {String} color * @param {Number} duration */ YUICONF 2009
    68. @event YUICONF 2009
    69. @property /** * Symbol for AM * @property AM * @type String */ YUICONF 2009
    70. @property YUICONF 2009
    71. @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
    72. @property + @attribute 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
    74. @method YUICONF 2009
    75. BUILDING DOCS YUICONF 2009
    76. http://bit.ly/yuidoc YUICONF 2009
    77. YUICONF 2009
    78. > 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
    79. example.sh parser_in="$HOME/src" parser_out=~/www/docs/parser generator_out=~/www/docs/generator template=$yuidoc_home/template YUICONF 2009
    80. 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
    81. 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
    82. Watch out for: YUICONF 2009
    83. .git Watch out for: .cvs .svn YUICONF 2009
    84. KEEPING DOCS RELEVANT YUICONF 2009
    85. Simple Rules 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
    89. ‣ Treat documentation comments like code YUICONF 2009
    90. ‣ Treat documentation comments like code ‣ Include as part of reviews 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
    93. TRY IT OUT YUICONF 2009
    94. git://github.com/saw/YUI-Doc-Example.git YUICONF 2009
    95. ./build.sh ant build 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
    98. ant build YUICONF 2009
    99. CUSTOM TEMPLATES YUICONF 2009
    100. Edit the stylesheet: templates/assets/api.css 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
    102. CUSTOM EVERYTHING YUICONF 2009
    103. Parser can be used for any Front end http://bit.ly/airdoc YUICONF 2009
    104. 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
    105. 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
    106. } }, 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
    107. 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": {
    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
    109. Parting Tips 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

    + Stephen WoodsStephen Woods, 3 weeks ago

    custom

    539 views, 5 favs, 0 embeds more stats

    An introduction to YUI Doc, a language neutral docu more

    More info about this document

    © All Rights Reserved

    Go to text version

    • Total Views 539
      • 539 on SlideShare
      • 0 from embeds
    • Comments 0
    • Favorites 5
    • Downloads 34
    Most viewed embeds

    more

    All embeds

    less

    Flagged as inappropriate Flag as inappropriate
    Flag as inappropriate

    Select your reason for flagging this presentation as inappropriate. If needed, use the feedback form to let us know more details.

    Cancel
    File a copyright complaint
    Having problems? Go to our helpdesk?

    Categories

    Tags

    -->
    Search
    RSS Feed
    What's new?

    © 2009 SlideShare Inc. All Rights Reserved