Getting started

Custom theme

Alternative usages

Extras

Introduction

SassDoc is doing quite a lot of things under the hood. In most cases, you won’t have to know anything about it but if you are willing to write your own theme, you might need to understand what’s going on. Especially, you’ll need to know what is being returned to the view so that you can actually write your templates.

Clarification: in the following examples, we are using C-style comments but it works exactly the same for inline comments as well. Please refer to the Annotations page for the syntax.

Note: you can run SassDoc in parse mode with the --parse CLI flag to output the data as JSON instead of generating a documentation directory.

Terminology

SassDoc uses the word “item” to describe either a variable, a function, a mixin or a placeholder. Technically speaking, an “item” is an object composed of:

  • a description defined at the top of the related documentation block comment, before any annotation;
  • a context, which is a sub-object containing the item’s name, its type (function, variable, mixin, placeholder), the lines at which it has been found in the file, and the its inner code (inside the declaration braces / variable content);
  • annotations: both those declared in the related documentation block comment, and those omitted with a default value.
{
  description: '',
  context: {
    name: '',
    type: '',
    code: '',
    line: {
      start: 0,
      end: 0,
    },
  },
  access: ['public'],
  group: ['undefined'],
}

Sorting

SassDoc will collect all these item in an array and sort them by group, alphabetic file path, and position in file.

[
  { /* Item */ },
  { /* Item */ },
]

@access

Will just return the string after the annotation as the access level.

/// @access private

An item will look like this:

{
  /* ... */
  access: 'private',
  /* ... */
}

@alias

Will list the alias in the alias key and add the alias item to the aliased key in the referenced item.

/// @alias other-item
@mixin alias-for-other-item() { /* ... */ }

Item alias-for-other-item:

{
  /* ... */
  alias: 'other-item',
  /* ... */
}

Item other-item will look like this:

{
  /* ... */
  aliased: [{
    /* ... */
    alias: ['alias-for-other-item'],
    /* ... */
  }]
  /* ... */
}

@author

/// @author Fabrice Weinberg

An item will look like this:

{
  /* ... */
  author: ['Fabrice Weinberg'],
  /* ... */
}

@content

/// @content The `@content` directive allows user ...

An item will look like this:

{
  /* ... */
  content: 'The `@content` dirctive allows user ...',
  /* ... */
}

@deprecated

/// @deprecated No longer in use

An item will look like this:

{
  /* ... */
  deprecated: 'No longer in use',
  /* ... */
}

@example

/// @example scss - basic usage
///   clamp(42, $min: 13, $max: 37)
///   // 37

An item will look like this:

{
  /* ... */
  example: [{
    'type': 'scss',
    'description': 'basic usage',
    'code': 'clamp(42, $min: 13, $max: 37)\n // 37',
  }],
  /* ... */
}

@group

/// @group Groupname

An item will look like this:

{
  /* ... */
  group: ['Groupname'],
  /* ... */
}

@ignore

This line will be just ignored.

/// @ignore Ignore the line

An item will look like this:

{
  /* ... */
  ignore: [],
  /* ... */
}
/// @link http://example.com Caption

An item will look like this:

{
  /* ... */
  link: [{
    'url': 'http://example.com',
    'caption': 'Caption',
  }],
  /* ... */
}

@output (synonym: @outputs)

/// @output Description of output styles

An item will look like this:

{
  /* ... */
  output: 'Description of output styles',
  /* ... */
}

@parameter (synonyms: @param, @arg, @argument)

/// @param {type} $name [default value] - description

An item will look like this:

{
  /* ... */
  parameter: [{
    'type': 'type',
    'name': 'name',
    'default': 'default value',
    'description': 'description',
  }],
  /* ... */
}

@property (synonym: @prop)

/// @prop {Function} base.default [default] - description
{
  /* ... */
  property: [{
     'type': 'Function',
     'path': 'base.default',
     'default': 'default',
     'description': 'description',
   }],
  /* ... */
}

@require (synonym: @requires)

The required item will automatically have a key named usedBy containing the whole referencing item.

/// @require {type} item - description <link>

An item will look like this:

{
  /* ... */
  require: [{
    'type': 'type',
    'name': 'item',
    'url': '<link>',
    'description': 'description',
    'item': { /* The whole required item */ },
  }],
  /* ... */
}

The referenced item will have a usedBy key that looks like:

{
  /* ... */
  usedBy: [{ /* The whole referencing item */ }],
  /* ... */
}

@return (synonym: @returns)

/// @return {type} description

An item will look like this:

{
  /* ... */
  'return': {
    type: 'type',
    description: 'description',
  },
  /* ... */
}

@since

Describes the version at which the documented item has been implemented or updated.

/// @since version description

An item will look like this:

{
  /* ... */
  since: [{
    version: 'version',
    description: 'description',
  }],
  /* ... */
}

@throw (synonym: @throws, @exception)

/// @throw Error related message

An item will look like this:

{
  /* ... */
  'throw': ['Error related message'],
  /* ... */
}

@todo

/// @todo Task to be done

An item will look like this:

{
  /* ... */
  todo: ['Task to be done'],
  /* ... */
}

@type

/// @type bool | string

An item will look like this:

{
  /* ... */
  type: 'bool | string',
  /* ... */
}