• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Beautiful Documentation with YUI Doc
 

Beautiful Documentation with YUI Doc

on

  • 16,675 views

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

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

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

Statistics

Views

Total Views
16,675
Views on SlideShare
16,558
Embed Views
117

Actions

Likes
16
Downloads
233
Comments
0

6 Embeds 117

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

Accessibility

Categories

Upload Details

Uploaded via as Apple Keynote

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • This talk is for anyone that writes apis other developers need to rely on <br /> YOU might be that other developer <br /> there is a lot to cover, this is an overview, check the website for examples
  • most people do <br /> but I hate undocumented code! <br /> most people do
  • That&apos;s fine if is regular code <br /> but if its an api..
  • No one will read your code <br /> if you provide an api, thats the point of an api
  • These are from real im conversations I found in my archive <br /> If "goodness" doesn&apos;t work <br /> why not self preservation? <br /> Good docs save you time
  • These are from real im conversations I found in my archive <br /> If "goodness" doesn&apos;t work <br /> why not self preservation? <br /> Good docs save you time
  • These are from real im conversations I found in my archive <br /> If "goodness" doesn&apos;t work <br /> why not self preservation? <br /> Good docs save you time
  • These are from real im conversations I found in my archive <br /> If "goodness" doesn&apos;t work <br /> why not self preservation? <br /> Good docs save you time
  • These are from real im conversations I found in my archive <br /> If "goodness" doesn&apos;t work <br /> why not self preservation? <br /> Good docs save you time
  • These are from real im conversations I found in my archive <br /> If "goodness" doesn&apos;t work <br /> why not self preservation? <br /> Good docs save you time
  • These are from real im conversations I found in my archive <br /> If "goodness" doesn&apos;t work <br /> why not self preservation? <br /> Good docs save you time
  • These are from real im conversations I found in my archive <br /> If "goodness" doesn&apos;t work <br /> why not self preservation? <br /> Good docs save you time
  • These are from real im conversations I found in my archive <br /> If "goodness" doesn&apos;t work <br /> why not self preservation? <br /> Good docs save you time
  • Almost every api you encounter has amazingly <br /> complete api documentation. Like Ruby on Rails
  • Almost every api you encounter has amazingly <br /> complete api documentation. Like Ruby on Rails
  • Like windows
  • and of course YUI <br /> How do they do that?
  • Documentation writing usually goes something like this <br /> People try all types of solutions to this issue, policy, templates, rules
  • Documentation writing usually goes something like this <br /> People try all types of solutions to this issue, policy, templates, rules
  • Documentation writing usually goes something like this <br /> People try all types of solutions to this issue, policy, templates, rules
  • Documentation writing usually goes something like this <br /> People try all types of solutions to this issue, policy, templates, rules
  • Documentation writing usually goes something like this <br /> People try all types of solutions to this issue, policy, templates, rules
  • Documentation writing usually goes something like this <br /> People try all types of solutions to this issue, policy, templates, rules
  • Documentation writing usually goes something like this <br /> People try all types of solutions to this issue, policy, templates, rules
  • Documentation writing usually goes something like this <br /> People try all types of solutions to this issue, policy, templates, rules
  • Documentation writing usually goes something like this <br /> 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 <br /> Some really read the code (doxygen, phpdocumentor) and will kind of work <br /> with no comments
  • YUI doesn&apos;t read the code <br /> takes comment blocks <br /> turns it into pretty documentation
  • YUI doesn&apos;t read the code <br /> takes comment blocks <br /> turns it into pretty documentation
  • language neutral, generated (mostly) from comment blocks <br /> works with any language <br /> lets you describe the code however makes sense...in other words supports all those strange <br /> idioms in javascript
  • language neutral, generated (mostly) from comment blocks <br /> works with any language <br /> lets you describe the code however makes sense...in other words supports all those strange <br /> idioms in javascript
  • language neutral, generated (mostly) from comment blocks <br /> works with any language <br /> lets you describe the code however makes sense...in other words supports all those strange <br /> idioms in javascript
  • Downsides
  • Downsides
  • Downsides
  • Beautiful documentation is like beautiful code, it is efficient and elegant. <br /> Its most important traits accuracy, docs should match the api <br /> complete: no one likes an undocumented feature <br /> useable: users are developers, if they can&apos;t find the docs, they might as well not exist <br /> 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. <br /> Its most important traits accuracy, docs should match the api <br /> complete: no one likes an undocumented feature <br /> useable: users are developers, if they can&apos;t find the docs, they might as well not exist <br /> 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. <br /> Its most important traits accuracy, docs should match the api <br /> complete: no one likes an undocumented feature <br /> useable: users are developers, if they can&apos;t find the docs, they might as well not exist <br /> 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. <br /> Its most important traits accuracy, docs should match the api <br /> complete: no one likes an undocumented feature <br /> useable: users are developers, if they can&apos;t find the docs, they might as well not exist <br /> understandable: the docs should actually make sense. Sadly this can&apos;t be automated
  • Comments describe whats going on <br /> each block can have ONLY one tag <br /> 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 <br /> but consistency is a good policy
  • module is a submodule of a parent module. <br /> YUI 3.x anim-scroll is a submodule of anim. <br /> A submodule encompasses a subset of the parent module&apos;s functionality.
  • module is a submodule of a parent module. <br /> YUI 3.x anim-scroll is a submodule of anim. <br /> 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. <br /> YUI 3.x anim-scroll is a submodule of anim. <br /> 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 <br /> or YUI 3 attribute, like in widget
  • Method docs are the meat of api docs <br /> these must be complete and good <br /> data types are really important
  • Lots of command line options here <br /> don&apos;t stress, write a build script! <br /> if you are confused try -h
  • A simple build script <br /> just an example <br /> your project won&apos;t work
  • A simple build script <br /> just an example <br /> your project won&apos;t work

Beautiful Documentation with YUI Doc Beautiful Documentation with YUI Doc Presentation Transcript