Documentation Style Guide - MattMcAdams/stratus GitHub Wiki

Documentation for this project is generated with Sassdoc. This document serves as a guide to how documentation in this project should be formatted, but if you'd like to know more about the available annotations, please refer to the Sassdoc documentation.

Documentation should precede each variable, function, and mixin and have the following organization:

/// --------------------------------------------------------------------------
/// Name of member                            |
/// Description, written in markdown          | ---- Meta Information
/// @access [private | public]                |
///
/// @requires member (module)                 | ---- Dependencies
///
/// @param {type} $param [default value]      | ---- Inputs
///   Description                             |
///
/// @returns {type}                           | ---- Outputs
/// --------------------------------------------------------------------------

Meta Information

  • Description should be a short explanation of what this function does
  • The @access annotation is used to show if the member is public or private. Private members are not forwarded with the rest of Stratus unless the module is used directly.

Dependencies

Dependencies should be ordered as follows:

  1. Local members
  2. Built in Sass modules
  3. Other Stratus modules
  4. Stratus configuration
/// @requires $config-foo
/// @requires sass.math (sass:math)
/// @requires stratus.bar (core)
/// @requires config.baz (config)

Inputs

All inputs should use the @param annotation rather than one of it's aliases. See Sassdoc for more.

Input types

Multiple types should be separated by pipes |.

  • number(unit)
    • unit can be a css unit, 'unitless', or 'with unit'
  • boolean
  • string
  • key($map)
  • keyword['string'|'string'|'string']
  • color(type)
    • type can be any valid css color format, or can be omitted.

Outputs

At the end of the comment block, list what the function returns and the errors it throws