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
    ...
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
True Stories of Bad Documentation




YUICONF 2009
True Stories of Bad Documentation




YUICONF 2009
WRITING DOCS



YUICONF 2009
YUICONF 2009
How do they make those wonderful
Docs?




YUICONF 2009
How do they make those wonderful
Docs?




YUICONF 2009
How do they make those wonderful
Docs?




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 Bug...
YUICONF 2009
Write Code




YUICONF 2009
Write Code



               Have Docs



YUICONF 2009
Write Code

                (MAGIC)

               Have Docs



YUICONF 2009
(MAGIC)




YUICONF 2009
(MAGIC)



YUICONF 2009
YUICONF 2009
CppDoc
          Doxygen
           JavaDoc
    PhpDocumentor
             JSDoc
           YUI Doc
             YARD




...
CppDoc
          Doxygen
           JavaDocDoc Generators
    PhpDocumentor Better Living
             JSDoc Through Autom...
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
  ...
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
   ...
/**
    * Test Java Module Description
    * @module lang.javatest
    */
    import java.util.*;

    /**
    * This is t...
#!/usr/bin/env python
    '''
    /**
    * Test Python File
    * @module testpy
    */
    '''
    import os, sys, strin...
=begin
   /**
   * Module Info for test Ruby File
   * @module lang.rubytest
   */
   =end
   require 'rubygems'
   requir...
/**
                  * This method syncs the value of time object,
                  * including building the strings for...
language-neutral




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 ...
language-neutral




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...
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
               ‣ U...
USING
   YUI DOC



YUICONF 2009
Sample Project
      My Project

          compression

         lzw.js

         lzw-lite.js

         widgets

         ...
Project Structure




YUICONF 2009
Project Structure


                                  Project



                   Module                      Module
   ...
Comment Blocks




YUICONF 2009
Comment Blocks


    /**
      * Description
      * @tag tagValue
      * @secondaryTag secondaryValue
      */




YUICO...
Primary Tags
    ‣ @module
    ‣ @class
    ‣ @property
    ‣ @event
    ‣ @method




YUICONF 2009
Secondary Tags
    ‣ @submodule   ‣ @extends
    ‣ @namespace   ‣ @config




                        *YUI Specific
YUICONF ...
@param & @return
Datatypes!

    @param {type} name description
    @return {type} description




YUICONF 2009
Object



        {}
                 Array
                String
@param         Boolean   Name Description
             ...
@module




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

  /**
...
@module




YUICONF 2009
@class
 /**
  * A YUI timepicker widget
  *
  * @class Timepicker
  * @constructor
  * @namespace Y.Saw
  * @extends Widge...
@class




YUICONF 2009
@event

     /**
      * Fires when a new day begins
      *
      * @event dawn
      * @param {String} color
      * @pa...
@event




YUICONF 2009
@property


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




YUICONF 2009
@property




YUICONF 2009
@property + @attribute

      /**
       * @property Timepicker.ATTRS
       * @type Object
       * @protected
       * @...
@property + @attribute




YUICONF 2009
@method
/**
 * Utility method that returns the size
 * of a unicode string in bytes
 * @method strSize
 * @param {String}s...
@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...
example.sh
          parser_in="$HOME/src"
          parser_out=~/www/docs/parser
          generator_out=~/www/docs/gener...
yourbuild.sh
          parser_in="$HOME/src"
          parser_out=~/www/docs/parser
          generator_out=~/www/docs/gen...
Slide Title
Slide Content

       <target name="doc">
           <mkdir dir="${tmp_dir}" />
           <mkdir dir="${tmp_d...
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
         docu...
Simple Rules



       ‣ Generate  documentation as
         part of the build
       ‣ Don't manually check
         docu...
‣ 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
        ...
‣ Treat documentation comments
 like code


       ‣ Include as part of reviews
       ‣ Comments are source, docs
       ...
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 loc...
./build.sh
  ant build
#!/bin/sh
                                                        <?xml version="1.0"?>
#first do t...
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
          ...
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
          generato...
The YUI Doc Parser Works Alone

          parser_in="$HOME/src"
          parser_out= ~/www/docs/parser
          generato...
}
                      },


The YUI Doc Parser Works Alone
                      "file": "lzw.js",
                      ...
The YUI Doc Parser Works Alone
 ~/www/docs/parser/parsed.json
 Complete JSON Representation of Documentation
             ...
And Code Highlighting too!
 ~/www/docs/parser /lzw.js.highlighted

     (function(){

         var STARTPOINT = 256;

    ...
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 doc...
Stephen Woods
               @ysaw
               Y!IM: stephenwoods_corp




YUICONF 2009
Upcoming SlideShare
Loading in...5
×

Beautiful Documentation with YUI Doc

16,373

Published on

An introduction to YUI Doc, a language neutral documentation generator, used to generate the API Docs for YUI.

Video here: http://bit.ly/1jDyAm

Published in: Technology, Education
0 Comments
18 Likes
Statistics
Notes
  • Be the first to comment

No Downloads
Views
Total Views
16,373
On Slideshare
0
From Embeds
0
Number of Embeds
2
Actions
Shares
0
Downloads
249
Comments
0
Likes
18
Embeds 0
No embeds

No notes for slide
  • 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&apos;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 &quot;goodness&quot; doesn&apos;t work
    why not self preservation?
    Good docs save you time
  • These are from real im conversations I found in my archive
    If &quot;goodness&quot; doesn&apos;t work
    why not self preservation?
    Good docs save you time
  • These are from real im conversations I found in my archive
    If &quot;goodness&quot; doesn&apos;t work
    why not self preservation?
    Good docs save you time
  • These are from real im conversations I found in my archive
    If &quot;goodness&quot; doesn&apos;t work
    why not self preservation?
    Good docs save you time
  • These are from real im conversations I found in my archive
    If &quot;goodness&quot; doesn&apos;t work
    why not self preservation?
    Good docs save you time
  • These are from real im conversations I found in my archive
    If &quot;goodness&quot; doesn&apos;t work
    why not self preservation?
    Good docs save you time
  • These are from real im conversations I found in my archive
    If &quot;goodness&quot; doesn&apos;t work
    why not self preservation?
    Good docs save you time
  • These are from real im conversations I found in my archive
    If &quot;goodness&quot; doesn&apos;t work
    why not self preservation?
    Good docs save you time
  • These are from real im conversations I found in my archive
    If &quot;goodness&quot; doesn&apos;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&apos;t read the code
    takes comment blocks
    turns it into pretty documentation
  • YUI doesn&apos;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&apos;t find the docs, they might as well not exist
    understandable: the docs should actually make sense. Sadly this can&apos;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&apos;t find the docs, they might as well not exist
    understandable: the docs should actually make sense. Sadly this can&apos;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&apos;t find the docs, they might as well not exist
    understandable: the docs should actually make sense. Sadly this can&apos;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&apos;t find the docs, they might as well not exist
    understandable: the docs should actually make sense. Sadly this can&apos;t be automated
  • Comments describe whats going on
    each block can have ONLY one tag
    and as many secondaryTags as you like
  • I&apos;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&apos;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&apos;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&apos;s functionality.
  • Events are fundemental to js, and need documenting, remember events don&apos;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&apos;t stress, write a build script!
    if you are confused try -h
  • A simple build script
    just an example
    your project won&apos;t work
  • A simple build script
    just an example
    your project won&apos;t work
  • Beautiful Documentation with YUI Doc

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

      Clipping is a handy way to collect important slides you want to go back to later.

    ×