sassdoc

SassDoc

SassDoc. Like JSDoc, but for Sass files.

Example

Function/mixin

// Function description
// ... on several lines if you will
// ---
// @access private
// ---
// @alias other-function
// ---
// @requires dependency-function
// ---
// @param {*}       $parameter-name            - description of the parameter
// @param {String}  $other-parameter (default) - parameter with a default value
// @param {ArgList} $args                      - extra parameters
// ---
// @throws `$other-parameter` must be a string.
// ---
// @return {String | Null} description of the returned value

@function dummy-function($parameter-name, $other-parameter: 'default', $args...) {
  // ...
}

Variable

// @var {Bool} - Defines whether the library should support legacy browsers (e.g. IE8).
$legacy-support: true !global;

Preview

Note: it works exactly the same with mixins.

Installation

npm install -g sassdoc

Usage

Command line

sassdoc <src> <dest> [options]

Arguments

1. <src> Path to your Sass folder.
2. <dest> Path to the destination folder.

Options

• -h, --help: bring help
• -v, --verbose: run in verbose mode

Node API

var sassdoc = require('sassdoc');

sassdoc.parse(__dirname + '/sass').then(function (items) {
  console.log(items);
})

Yielding a result like this:

[
  {
    'parameters': [
      { 'type': '*', 'name': 'parameter-name', 'default': undefined, 'description': 'description of the parameter' },
      { 'type': 'String', 'name': 'other-parameter', 'default': 'default', 'description': 'parameter with a default value' },
      { 'type': 'ArgList', 'name': 'args', 'default': undefined, 'description': 'extra parameters' }
    ],
    'throws': ['`$other-parameter` must be a string.'],
    'todos': [],
    'alias': false,
    'aliased': 'other-function',
    'links': [],
    'requires': ['dependency-function'],
    'description': 'Function description\n... on several lines if you will',
    'access': 'private',
    'deprecated': false,
    'author': false,
    'returns': {
      'type': ['String', 'Null'],
      'description': 'description of the returned value'
    },
    'type': 'function',
    'name': 'dummy-function'
  }
  /*,
    ... other documented mixins/functions.
  */
]

API Documentation

Name

Name of the documented function/mixin is self parsed, hence @name doesn't exist.

Description

Describes the documented function/mixin. Any line which is nota valid token or a separator line is considered part of the description.

@access

Defines the access of the documented function/mixin. None is considered @access public.

// @access private
// @access public
// @access protected

It is also possible to define access like this:

// @private
// @public
// @protected

@alias

Defines if the documented function/mixin is an alias of another function.

// @alias other-function

@author

Describes the author of the documented function/mixin.

// @author Author's name

@deprecated

Defines if the documented documented function/mixin is deprecated. Message is optional.

// @deprecated
// @deprecated Deprecation related message

@ignore

Defines a line which won't be documented. Multiple @ignore allowed on the same function/mixin.

// @ignore Message

@link

Describes a link. Multiple @link allowed on the same function/mixin.

// @link http://some.url
// @link http://some.url Optional caption

@param (synonyms: @arg, @argument)

Describes a parameter of the documented function/mixin. Default value and description are optional.

// @param {type | othertype} $name
// @param {type} $name - description
// @param {type} $name (default value) - description of the parameter

Type is any of: arglist, bool, color, list, map, null, number, string or * when any type is allowed. Case insensitive.

@requires

Defines if the documented function/mixin requires any other function/mixin. Multiple @requires allowed on the same function/mixin.

// @requires other-function

@returns (synonym: @return)

Describes the return statement of the documented function/mixin. Description is optional.

// @returns {type | othertype}
// @returns {type} Description of the return statement

Type is one of: arglist, bool, color, list, map, null, number, string or * when any type is allowed. Case insensitive.

@since

Describes the version at which the documented function/mixin has been implemented.

// @since 4.2

@throws (synonym: @exception)

Describes the error thrown by the documented function/mixin. Multiple @throws allowed on the same function/mixin.

// @throws Error related message

@todo

Defines any task to do regarding the documented function/mixin. Multiple @todo allowed on the same function/mixin.

// @todo Task to be done

@var

Describes a variable. Has nothing to do with function/mixin.

// @var {Bool} - Defines whether the library should support legacy browsers (e.g. IE8).
$legacy-support: true !global;

Scope is defined by the (lack of) use of !global.

Credits

Huge thanks to Valérian Galliat for the help.

Changelog

0.3.3

• Who knows?