зеркало из https://github.com/telerik/dss.git
184255e725 | ||
---|---|---|
.github/workflows | ||
.vscode | ||
playground | ||
test | ||
.commitlintrc.json | ||
.editorconfig | ||
.eslintignore | ||
.eslintrc | ||
.gitignore | ||
.npmignore | ||
CHANGELOG.md | ||
LICENSE.md | ||
README.md | ||
dss.js | ||
package-lock.json | ||
package.json | ||
release.config.js |
README.md
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
Example Comment Block
/**
* @name Button
* @description Your standard form button.
*
* @state :hover - Highlights when hovering.
* @state :disabled - Dims the button when disabled.
* @state .primary - Indicates button is the primary action.
* @state .smaller - A smaller button.
*
* @example
* <span>
* <button>This is a button</button>
* </span>
*
* @deprecated 123.321
* @deprecatedDescription This is deprecated.
*
* @group Buttons
* @type Color
* @subtype Text-Color
* @key $button-bg
*
* @param {string} par1 - ParmOne description.
* @param {function} par2 - ParamTwo description.
* @returns {number} - Return description.
*/
or
/// @name Button
/// @description Your standard form button.
///
/// @state :hover - Highlights when hovering.
/// @state :disabled - Dims the button when disabled.
/// @state .primary - Indicates button is the primary action.
/// @state .smaller - A smaller button.
///
/// @example
/// <span>
/// <button>This is a button</button>
/// </span>
///
/// @deprecated 123.321
/// @deprecatedDescription This is deprecated.
///
/// @group Buttons
/// @type Color
/// @subtype Text-Color
/// @key $button-bg
///
/// @param {string} par1 - ParmOne description.
/// @param {function} par2 - ParamTwo description.
/// @returns {number} - Return description.
///
Basic Usage
// Require/read a file
const fs = require('fs');
const dss = require('dss');
const file = fs.readFileSync('styles.scss');
// Run DSS Parser
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
andexample
parsers allow usage of multi-line comments. - If a comment block starts without an annotation, the parser sets this text as
description
. However, if adescription
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
andparam
parsers are returning an array of all the relevant annotations. - If not defined, the parser tries to assume the
type
andkey
values based on the next line. - The
group
,type
, andsubtype
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:
// Matches @link
dss.parser('link', (i, line, block, file) => {
// Replace link with HTML wrapped version
const exp = /(b(https?|ftp|file)://[-A-Z0-9+&@#/%?=~_|!:,.;]*[-A-Z0-9+&@#/%=~_|])/ig;
return line.replace(exp, "<a href='$1'>$1</a>");
});
// Matches @version
dss.parser('version', (i, line, block, file) => {
return line;
});