Herman 5.0.0-beta.2

SassDoc Annotations

Herman supports all the core SassDoc annotations. This page includes samples of every core annotation type, so you can see what they look like in Herman.

Related

http://sassdoc.com/annotations/ [external]

Extra Commentary

Herman allows you to write “prose” markdown blocks, to help introduce groups, or add narrative flow between documented items.

Note that while SassDoc allows annotation comments to be separated from the documented code by newlines, Herman considers documentation to be free-floating “prose” if it is separated from documented code by one or more newlines.

This change often breaks the autofill functionality of the core SassDoc annotations, so Herman skips the annotation autofill functionality for any “prose” items.

Prose blocks can also include examples, and other annotations:

/// Prose blocks can also include examples, and other annotations:
/// @example scss
///   .private::after {
///     content: samples.$private;
///   }
/// @link http://sassdoc.com/configuration/#autofill

Example

scss 
.private::after {
  content: samples.$private;
}
css compiled 
.private::after {
  content: "for internal use only";
}

@function herman-sample()

aliased as sample-alias(), sample-alias-two()

This is a sample function. You can actually put much more text in here, and include markdown. Lorem markdownum rapite neque loquentis pro inque; nullaque triones promisistis quaque. Non iura oves creatas mixta gente torum Caune. Huius sacra corpora refert celeberrima luctus tibi cornua, nec qui illum poteram, et eundi recalfecit efficiens isdem superi. Alii virginibusque vultus certa socios venae ferrove finis longave, pignus duros nubifer!

  • Tenuatus percussae tanta iudice Hippolytus miseram inmunis
  • Ture Iovis holus est et vere
  • Domus cum quid meae erras
  • Quam apta fata puppis ergo solis praeteriti

Since 1.0.0:

Adding samples files to the documentation.

Author:

Parameters & Return

$one: (number)

The first parameter is required, because no default is given

$two: $one (number)

Our second parameter defaults to the value of our first one

$three: 'three' (string)

Looks like this one takes a string instead

@return (list)

All three of the arguments in order

@error

Please provide values for all three parameters

Example

scss describe examples if you want… 
.example::before {
  content: samples.herman-sample(1, 2);
}
css compiled 
.example::before {
  content: 1 2 "three";
}

Related

OddBird Home Page [external]

@function sample-alias()

Used By

@function sample-alias()

@function sample-alias-two()

To-do List

  • Create more samples like this one

  • Add more todo items

@function sample-alias() [deprecated]

alias for herman-sample()

This is a sample function alias.

DEPRECATED:

I don’t think this alias is useful anymore

Requires

@function herman-sample()

@function sample-alias-two() [deprecated]

alias for herman-sample()

This is a sample function alias.

DEPRECATED:

Doesn’t seem to work without a message

Requires

@function herman-sample()

@mixin before-sample()

Mixins can optionally accept a @content block, passed in brackets. This example creates a generated element :before the element it is used on.

Parameters & Output

$content: (String)

A value for the content property

$list…: (arglist)

Sass also allows arglists!

@content (code block)

Any other styles that should be applied to the ::before element

{CSS output} (code block)

A ::before pseudo-element, with the content property established, and any passed-in styled applied.

Example

scss 
.item {
  @include samples.before-sample('Test One: ') {
    color: red;
  }
}
css compiled 
.item::before {
  content: "Test One: ";
  color: red;
}

$private (*) [private]

scss 
$private: 'for internal use only';

Private variables will display unless you set access: ['public'] in your SassDoc config.

$basic-value (*)

scss 
$basic-value: if(not 'social', $private, 'hello world');

The basics for documenting your average non-map variable.

Requires

$private (*) [private]

Used By

$map-value

$map-value (map)

scss 
$map-value: (
  'morning': $basic-value,
  'evening': $private,
);

You can add properties when documenting map variables.

Map Properties

'morning': $basic-value (string)

What to say in the morning when you get up

'evening': $private (string)

What to say in the evening before bed

Requires

$basic-value (*)

We can require other variables, and explain why

$private (*) [private]

We can also override the link