@progress/dss/README.md

Documented Style Sheets

# DSS

This is a fork of [DSS](https://github.com/DSSORG/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

```css
/**
 * @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

```scss
/// @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

```javascript
// 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

```json
[{
    "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": " &lt;span&gt;\n     &lt;button&gt;This is a button&lt;/button&gt;\n &lt;/span&gt;"
    },
    "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

1. Only the `description` and `example` parsers allow usage of multi-line comments.
1. 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.
1. If more than one `example` is provided, the parser returns an array of examples.
1. The `state` and `param` parsers are returning an array of all the relevant annotations.
1. If not defined, the parser tries to assume the `type` and `key` values based on the next line.
1. 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:

1. `return` - `returns`
1. `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:

```javascript
// 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>");
});
```

```javascript
// Matches @version
dss.parser('version', (i, line, block, file) => {
    return line;
});
```