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

npm install --save-dev stylelint-sassdoc

Make sure you already included your stylelint job to package.json

// all scss files
"stylelint": "stylelint "**/*.scss" --config ./your.stylelint.config.js --fix -s scss"

Add stylelint plugin and sassdoc rules to stylelint config

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

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 documentation

Development

IMPORTANT

postCSS does some on-the-fly processing, so a SCSS comment like:

/// my comment

gets output (and compared) like this:

/*/ my comment */

This makes regEx comparisons more difficult. Check out the helper functions adjacentLineIsSCSSComment, nodeToString and getSourceArray for this.

License

MIT.