docs(LOADER): update JSDoc

webpack-contrib · Aug 8, 2018 · 95de4c1 · 95de4c1
1 parent ea68a42
commit 95de4c1
Show file tree

Hide file tree

Showing 7 changed files with 197 additions and 71 deletions.
diff --git a/LOADER.md b/LOADER.md
diff --git a/docs/LOADER.md b/docs/LOADER.md
@@ -0,0 +1,130 @@
+## Modules
+
+<dl>
+<dt><a href="#module_postcss-loader">postcss-loader</a></dt>
+<dd></dd>
+</dl>
+
+## Classes
+
+<dl>
+<dt><a href="#SyntaxError">SyntaxError</a> ⇐ <code>Error</code></dt>
+<dd></dd>
+<dt><a href="#Warning">Warning</a> ⇐ <code>Error</code></dt>
+<dd></dd>
+</dl>
+
+## Functions
+
+<dl>
+<dt><a href="#loader">loader(css, map)</a> ⇒ <code>cb</code></dt>
+<dd><p><strong>PostCSS Loader</strong></p>
+<p>Loads &amp;&amp; processes CSS with <a href="https://github.com/postcss/postcss">PostCSS</a></p>
+</dd>
+<dt><a href="#parseOptions">parseOptions(exec, parser, syntax, stringifier, plugins)</a> ⇒ <code>Promise</code></dt>
+<dd><p><strong>PostCSS Options Parser</strong></p>
+<p>Transforms the loader options into a valid postcss config <code>{Object}</code></p>
+</dd>
+</dl>
+
+<a name="module_postcss-loader"></a>
+
+## postcss-loader
+**Requires**: <code>module:path</code>, <code>module:loader-utils</code>, <code>module:schema-utils</code>, <code>module:postcss</code>, <code>module:postcss-load-config</code>, <code>module:./options.js</code>, <code>module:./Warning.js</code>, <code>module:./SyntaxError.js</code>  
+**Version**: 3.0.0  
+**Author**: Andrey Sitnik (@ai) <andrey@sitnik.ru>  
+**License**: MIT  
+<a name="SyntaxError"></a>
+
+## SyntaxError ⇐ <code>Error</code>
+**Kind**: global class  
+**Extends**: <code>Error</code>  
+<a name="new_SyntaxError_new"></a>
+
+### new SyntaxError(err)
+**PostCSS Syntax Error**
+
+Loader wrapper for postcss syntax errors
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| err | <code>Object</code> | CssSyntaxError |
+
+<a name="Warning"></a>
+
+## Warning ⇐ <code>Error</code>
+**Kind**: global class  
+**Extends**: <code>Error</code>  
+<a name="new_Warning_new"></a>
+
+### new Warning(warning)
+**PostCSS Plugin Warning**
+
+Loader wrapper for postcss plugin warnings (`root.messages`)
+
+
+| Param | Type | Description |
+| --- | --- | --- |
+| warning | <code>Object</code> | PostCSS Warning |
+
+<a name="loader"></a>
+
+## loader(css, map) ⇒ <code>cb</code>
+**PostCSS Loader**
+
+Loads && processes CSS with [PostCSS](https://github.com/postcss/postcss)
+
+**Kind**: global function  
+**Returns**: <code>cb</code> - cb Result  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| css | <code>String</code> | Source |
+| map | <code>Object</code> | Source Map |
+
+
+* [loader(css, map)](#loader) ⇒ <code>cb</code>
+    * [.cb](#loader.cb) : <code>function</code>
+    * [.cb](#loader.cb) : <code>function</code>
+
+<a name="loader.cb"></a>
+
+### loader.cb : <code>function</code>
+**Kind**: static typedef of [<code>loader</code>](#loader)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| null | <code>Object</code> | Error |
+| css | <code>String</code> | Result (JS Module) |
+| map | <code>Object</code> | Source Map |
+
+<a name="loader.cb"></a>
+
+### loader.cb : <code>function</code>
+**Kind**: static typedef of [<code>loader</code>](#loader)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| null | <code>Object</code> | Error |
+| css | <code>String</code> | Result (Raw Module) |
+| map | <code>Object</code> | Source Map |
+
+<a name="parseOptions"></a>
+
+## parseOptions(exec, parser, syntax, stringifier, plugins) ⇒ <code>Promise</code>
+**PostCSS Options Parser**
+
+Transforms the loader options into a valid postcss config `{Object}`
+
+**Kind**: global function  
+**Returns**: <code>Promise</code> - PostCSS Config  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| exec | <code>Boolean</code> | Execute CSS-in-JS |
+| parser | <code>String</code> \| <code>Object</code> | PostCSS Parser |
+| syntax | <code>String</code> \| <code>Object</code> | PostCSS Syntax |
+| stringifier | <code>String</code> \| <code>Object</code> | PostCSS Stringifier |
+| plugins | <code>Array</code> \| <code>Object</code> \| <code>function</code> | PostCSS Plugins |
+
diff --git a/package.json b/package.json
@@ -29,7 +29,7 @@
   "scripts": {
     "lint": "standard --env jest",
     "test": "jest --env node --verbose --coverage",
-    "docs": "jsdoc2md src/*.js > LOADER.md",
+    "docs": "jsdoc2md src/*.js > docs/LOADER.md",
     "clean": "rm -rf coverage test/outputs",
     "release": "standard-version"
   },

diff --git a/src/Error.js b/src/Error.js
@@ -1,3 +1,13 @@
+/**
+ * **PostCSS Syntax Error**
+ *
+ * Loader wrapper for postcss syntax errors
+ *
+ * @class SyntaxError
+ * @extends Error
+ *
+ * @param {Object} err CssSyntaxError
+ */
 class SyntaxError extends Error {
   constructor (err) {
     super(err)

diff --git a/src/Warning.js b/src/Warning.js
@@ -1,3 +1,13 @@
+/**
+ * **PostCSS Plugin Warning**
+ *
+ * Loader wrapper for postcss plugin warnings (`root.messages`)
+ *
+ * @class Warning
+ * @extends Error
+ *
+ * @param {Object} warning PostCSS Warning
+ */
 class Warning extends Error {
   constructor (warning) {
     super()

diff --git a/src/index.js b/src/index.js
@@ -11,33 +11,18 @@ const SyntaxError = require('./Error.js')
 const parseOptions = require('./options.js')
 
 /**
- * PostCSS Loader
+ * **PostCSS Loader**
  *
- * > Loads && processes CSS with [PostCSS](https://github.com/postcss/postcss)
- *
- * @author Andrey Sitnik (@ai) <andrey@sitnik.ru>
- *
- * @license MIT
- * @version 2.0.0
- *
- * @requires path
- *
- * @requires loader-utils
- * @requires schema-utils
- *
- * @requires postcss
- * @requires postcss-load-config
- *
- * @requires Error
+ * Loads && processes CSS with [PostCSS](https://github.com/postcss/postcss)
  *
  * @method loader
  *
- * @param  {String} css Source
- * @param  {Object} map Source Map
+ * @param {String} css Source
+ * @param {Object} map Source Map
  *
- * @return {cb} cb      Result
+ * @return {cb} cb Result
  */
-module.exports = function loader (css, map, meta) {
+function loader (css, map, meta) {
   const options = Object.assign({}, getOptions(this))
 
   validateOptions(require('./options.json'), options, 'PostCSS Loader')
@@ -192,9 +177,9 @@ module.exports = function loader (css, map, meta) {
            * @memberof loader
            * @callback cb
            *
-           * @param {Object} null   Error
-           * @param {String} result Result (JS Module)
-           * @param {Object} map    Source Map
+           * @param {Object} null Error
+           * @param {String} css  Result (JS Module)
+           * @param {Object} map  Source Map
            */
           cb(null, `module.exports = ${JSON.stringify(css)}`, map)
 
@@ -223,3 +208,25 @@ module.exports = function loader (css, map, meta) {
       : cb(err)
   })
 }
+
+/**
+ * @author Andrey Sitnik (@ai) <andrey@sitnik.ru>
+ *
+ * @license MIT
+ * @version 3.0.0
+ *
+ * @module postcss-loader
+ *
+ * @requires path
+ *
+ * @requires loader-utils
+ * @requires schema-utils
+ *
+ * @requires postcss
+ * @requires postcss-load-config
+ *
+ * @requires ./options.js
+ * @requires ./Warning.js
+ * @requires ./SyntaxError.js
+ */
+module.exports = loader
diff --git a/src/options.js b/src/options.js
@@ -1,3 +1,18 @@
+/**
+ * **PostCSS Options Parser**
+ *
+ * Transforms the loader options into a valid postcss config `{Object}`
+ *
+ * @method parseOptions
+ *
+ * @param {Boolean} exec Execute CSS-in-JS
+ * @param {String|Object} parser PostCSS Parser
+ * @param {String|Object} syntax PostCSS Syntax
+ * @param {String|Object} stringifier PostCSS Stringifier
+ * @param {Array|Object|Function} plugins PostCSS Plugins
+ *
+ * @return {Promise} PostCSS Config
+ */
 function parseOptions ({ exec, parser, syntax, stringifier, plugins }) {
   if (typeof plugins === 'function') {
     plugins = plugins.call(this, this)