sassdoc

SassDoc

SassDoc. Like JSDoc, but for Sass files.

Example

// Function description
// ... on several lines if you will
// ---
// @access private
// ---
// @alias other-function
// ---
// @param {Literal} $parameter-name            - description of the parameter
// @param {String}  $other-parameter (default) - parameter with a default value
// @param {ArgList} $args                      - extra parameters
// ---
// @return {String | null} description of the returned value

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

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

[WIP] Node API

var sassdoc = require('sassdoc');

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

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 is optional. @arg, @argument and @parameter are accepted as well.

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

@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}
// @returns {type} Description of the return statement

@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

Credits

Huge thanks to Valérian Galliat for the help.