Loading...

Documenting Interfaces

Darcy Clarke - @darcy

CSS: What's the default positioning of an element?

What's documentation?

Time

  • *Past
  • *Present
  • *Future

Modes

  • *Creation
  • *Consumption

Time & Modes

  • *Creation - Future
  • *Consumption - Past

The Future
Can be Dangerous

Types

  • *Concept
  • *Tutorial
  • *Reference

EmberJS emberjs.com

Foundation foundation.zurb.com

BackboneJS backbonejs.org

*Reference

Documentation Should Be:

  • *Concise
  • *Descriptive
  • *Standard
  • *Easy to maintain

UI Documentation is hard:

  • *Requires Context
  • *Visual Queues
  • *Multiple stakeholders

*Generators

Natural Docs naturaldocs.org

PHP Docs phpdoc.org

Tom Doc tomdoc.org

*Comment Parsing

Comment Blocks

 /*
  * This is the description for my class.
  *
  * @class MyClass
  * @constructor
  */
/**
  * My method description.  Like other pieces of your comment blocks, 
  * this can span multiple lines.
  *
  * @method methodName
  * @param {String} foo Argument 1
  * @param {Object} config A config object
  * @param {String} config.name The name on the config object
  * @param {Function} config.callback A callback function on the config object
  * @param {Boolean} [extra=false] Do extra, optional work
  * @return {Boolean} Returns true on success
  */

What about UI?

What about CSS?

KSS - Ruby Gem warpspire.com/kss

KSS - Styleguide

// A button suitable for giving stars to someone.
//
// :hover             - Subtle hover highlight.
// .stars-given       - A highlight indicating you've already given a star.
// .stars-given:hover - Subtle hover highlight on top of stars-given styling.
// .disabled          - Dims the button to indicate it cannot be used.
//
// Styleguide 2.1.3.

KSS - Example warpspire.com/kss

KSS - Example warpspire.com/kss

KSS - Pros

  • *Dynamically generates an object
  • *Enforces structured commenting
  • *Encourages documentation of states
  • *Reduces documentation redundancy
  • *Works with SASS & LESS

KSS - Cons

  • *Multi-step process
  • *Commenting guideline isn't flexible
  • *Doesn't address context
  • *Doesn't addess inheritence

Can we do better?

long pause . . .

Documented Style Sheets

Warning - W.I.P.

What is it?

  • *A documentation tool
  • *A style guide
  • *A comment parser

DSS - Pros

  • *Single-step build process
  • *Flexible styleguide
  • *Template support
  • *Grunt.js Plugin

DSS - Cons

  • *Doesn't address context
  • *Doesn't addess inheritence

We're working on that . . .

DSS - Styleguide

/**
  * @name Button
  * @description Your standard form button.
  * 
  * @state :hover - Highlights when hovering.
  * @state :disabled - Dims the button when disabled.
  * @state .primary - Indicates button is the primary action.
  * @state .smaller - A smaller button
  * 
  * @markup
  *   <button>This is a button</button>
  */

More TBA . . .

at jQueryTO - March 2nd-3rd jqueryto.com