DSS
This is a fork of DSS.
DSS, Documented Style Sheets, is a comment styleguide and parser for CSS, LESS, SASS and SCSS code.
Generating Documentation
In most cases, you will want to include the DSS parser in a build step that will generate documentation files automatically.
Parser Example
or
Basic Usage
const fs = require('fs');
const dss = require('dss');
const file = fs.readFileSync('styles.scss');
dss.parse(file, {}, (parsed) => {
console.log(parsed.blocks);
});
Example Generated Object
[{
"name": "Button",
"description": "Your standard form button.",
"state": [
{
"name": ":hover",
"escaped": "pseudo-class-hover",
"description": "Highlights when hovering."
},
{
"name": ":disabled",
"escaped": "pseudo-class-disabled",
"description": "Dims the button when disabled."
},
{
"name": ".primary",
"escaped": "primary",
"description": "Indicates button is the primary action."
},
{
"name": ".smaller",
"escaped": "smaller",
"description": "A smaller button."
}
],
"example": {
"example": " <span>\n <button>This is a button</button>\n </span>",
"escaped": " <span>\n <button>This is a button</button>\n </span>"
},
"deprecated": "123.321",
"deprecatedDescription": "This is deprecated.",
"group": "buttons",
"type": "color",
"subtype": "text-color",
"key": "$button-bg",
"param": [
{
"type": "{string}",
"name": "par1",
"description": "ParmOne description."
},
{
"type": "{function}",
"name": "par2",
"description": "ParmTwo description."
}
],
"returns": {
"type": "{number}",
"name": null,
"description": "Return description."
}
}]
Parsers Specifics
- Only the
description
and example
parsers allow usage of multi-line comments. - If a comment block starts without an annotation, the parser sets this text as
description
. However, if a description
annotation is available, the parser overrides the non-annotation one. - If more than one
example
is provided, the parser returns an array of examples. - The
state
and param
parsers are returning an array of all the relevant annotations. - If not defined, the parser tries to assume the
type
and key
values based on the next line. - The
group
, type
, and subtype
parsers convert the string annotation to lowercase letters.
Parser Aliases
The parser aliases set their value in the key
of the main parser in the output JSON
.
DSS, by default, includes the following alias
- parser
pairs:
return
- returns
markup
- example
Modifying Parsers
DSS, by default, includes the name
, description
, state
, example
, deprecated
, deprecatedDescription
, group
, type
, subtype
, key
, param
, and returns
parsers of a comment block. You can add to or override these default parsers using the following:
dss.parser('link', (i, line, block, file) => {
const exp = /(b(https?|ftp|file)://[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/ig;
return line.replace(exp, "<a href='$1'>$1</a>");
});
dss.parser('version', (i, line, block, file) => {
return line;
});