Recommandé
Recommandé
Contenu connexe
Tendances
Tendances (20)
En vedette
En vedette (9)
Similaire à Beautiful Documentation with YUI Doc
Similaire à Beautiful Documentation with YUI Doc (20)
Dernier
Dernier (20)
Beautiful Documentation with YUI Doc
- 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
- 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
- 20. Write Code Have Docs YUICONF 2009
- 21. Write Code (MAGIC) Have Docs 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
- 31. YUI Doc A language-neutral way to automagically generate beautiful documentation 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
- 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
- 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
- 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
- 55. Project Structure Project Module Module ~/LZW ~/Timepicker Class Class Class LZW LZW-Lite Timepicker 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
- 63. @module /** * A javascript file compression library * @module Compression * @requires node, event */ /** * Provides LZW compression * @module Compression * @submodule Compression-LZW */ YUICONF 2009
- 65. @class /** * A YUI timepicker widget * * @class Timepicker * @constructor * @namespace Y.Saw * @extends Widget */ YUI.add('timepicker', function(Y){ YUICONF 2009
- 67. @event /** * Fires when a new day begins * * @event dawn * @param {String} color * @param {Number} duration */ YUICONF 2009
- 69. @property /** * Symbol for AM * @property AM * @type String */ 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
- 75. BUILDING DOCS 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
- 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
- 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
- 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
- 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
Notes de l'éditeur
- 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