stylelint plugin to check scss files for a valid sassdoc documentation Credits to https://github.com/anneangersbach
npm install stylelint-sassdocThis 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.
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"
`
$3
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,
...
}
`
$3
bash
npm run stylelint
`
Helpful links
| Link | Description |
| ------ | ------ |
| SassDoc Documentation | Check #Annotation and #File Annotation, to see what you have to check in your file |
| SassDoc Repo | useful to check how they validate things (example: @return) |
|SCSS Documentation| check valid arguments, etc|
|PostCSS API| this is what you will use to write the plugin! |
|Stylelint Developer Guide| How to write stylelint plugins|
|Stylelint Repo| stylelint utils, useful to re-use some code that's not an external module (yet)|
|RegExr| if you need to test some regexp|
|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
- 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
- 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 documentationDevelopment
> 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 /
``MIT.