stylelint-sassdoc/README.md

stylelint plugin to check scss files for a valid sassdoc documentation Credits to https://github.com/anneangersbach

# Stylelint SASSDoc Plugin

This plugin provides configurable rules to check  scss files for sassdoc comments.
It abides by the stylelint developer guide.

> private mixins, functions and variables are currently ignored. See Open issues for more information.

## Usage

### Install plugin
```bash
npm install --save-dev stylelint-sassdoc
```
Make sure you already included your stylelint job to package.json
```js
// all scss files
"stylelint": "stylelint "**/*.scss" --config ./your.stylelint.config.js --fix -s scss"
```
### Add stylelint plugin and sassdoc rules to stylelint config
```js
plugins: [
   'stylelint-sassdoc',
   ...
]

rules: {
   'sassdoc/atExample': [true, {
        severity: 'warning', // optional
    }],
    'sassdoc/atName': true,
    'sassdoc/atParameter': true,
    'sassdoc/atReturn': true,
    'sassdoc/commentblock-postercomment': true,
    'sassdoc/poster-comment': true,
    'sassdoc/variable-has-type': true,
    'sassdoc/function-is-documented': true,
    'sassdoc/mixin-is-documented': true,
   ...
}
```
### Run
```bash
npm run stylelint
```


## Helpful links

| Link | Description |
| ------ | ------ |
| [SassDoc Documentation](http://sassdoc.com/annotations/) | Check #Annotation and #File Annotation, to see what you have to check in your file |
| [SassDoc Repo](https://github.com/SassDoc/sassdoc/blob/master/src/annotation/annotations/return.js) | useful to check how they validate things (example: @return) |
|[SCSS Documentation](https://sass-lang.com/documentation/at-rules/function#arguments)| check valid arguments, etc|
|[PostCSS API](https://postcss.org/api/)| this is what you will use to write the plugin! |
|[Stylelint Developer Guide](https://stylelint.io/developer-guide/plugins)| How to write stylelint plugins|
|[Stylelint Repo](https://github.com/stylelint/stylelint/tree/master/lib/utils)| stylelint utils, useful to re-use some code that's not an external module (yet)|
|[RegExr](https://regexr.com/)| if you need to test some regexp|
|[Awesome Stylelint](https://github.com/stylelint/awesome-stylelint)| Plugin collection useful for further code inspiration|


## Open issues
  - **atReturn**
    - Fix RegEx for @return to work without whitespace (might be stylelint stringformatter bug)
  - **Optimise Utils**
    - Merge checkCommentsForReturn/-Name/-Group/-GroupName/-Params/-Example into one function with parameters for the regex(s) and the direction of the search.
  - [**atParam**](https://sass-lang.com/documentation/at-rules/function#arguments)
    - checking actual name of parameters
  - **poster comment**
    - description comes **before** any annotations
    - check for '/// string' between the last '/// @something' and the closing '////' of the poster comment
    - check for multiple poster comments (only 1 allowed)
    - create option for @group-name since it's a custom property
  - [**private things**](http://sassdoc.com/annotations/#access)
    - mixins, functions and variables that start with underscore '*_myColor*' need to be parsed differently.
      - either check that they aren't commented and throw an error if they are
      - or check that they have **@access private**
      - **CHALLENGE:** the first method conflicts in a way with the other rules, checking for parameters and returns etc. Either we need a separate rule for access private, or extend all the other rules for a check of private things.
  - helper to find all "/// @something" to make the next part simpler
  - optional annotations, to complete the plugin
    - alias
    - author
    - content
    - deprecated
    - ignore
    - link
    - output
    - property
    - require
    - see
    - since
    - throw
    - todo
- **performance**
  - try to reuse the sourceArray if it's used multiple times
- **testing**
  - Write tests with JEST: check stylelint-plugin documentation

## Development

> **IMPORTANT**

postCSS does some on-the-fly processing, so a SCSS comment like:
```scss
/// my comment
```
gets output (and compared) like this:
```scss
/*/ my comment */
```
This makes regEx comparisons more difficult. Check out the helper functions **adjacentLineIsSCSSComment**, **nodeToString** and **getSourceArray** for this.

## License

[MIT](https://raw.githubusercontent.com/stylelint/stylelint/master/LICENSE).