Documenting Interfaces
Darcy Clarke - @darcy
CSS: What's the default positioning of an element?
Time & Modes
- *Creation - Future
- *Consumption - Past
The Future
Can be Dangerous
Types
- *Concept
- *Tutorial
- *Reference
Documentation Should Be:
- *Concise
- *Descriptive
- *Standard
- *Easy to maintain
UI Documentation is hard:
- *Requires Context
- *Visual Queues
- *Multiple stakeholders
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
*/
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 - 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
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>
*/