feat(comments): add support for JavaDoc blocks parsing

dss.js

@@ -293,12 +293,13 @@ let dss = ( function() {
          * @returns {boolean} - Result of check.
          */
         let parseMultiLine = function( line ) {
-            let cleaned = line.replace( /\s*\/\*/, '' );
-            return cleaned.replace( /\*\//, '' );
+            let cleaned = line.replace( /\s*\/\*/, '' ).trim();
+            cleaned = cleaned.replace( /\*\//, '' );
+            return cleaned.replace( /^\*/, '' );
         };
         /* eslint-disable no-param-reassign */
         lines = String(lines);
-        lines.split( /\n/ ).forEach( function( line ) {
+        lines.split( /\n/ ).forEach(( line, index, linesArr ) => {
 
             lineNum = lineNum + 1;
             line = String(line);
@@ -333,8 +334,9 @@ let dss = ( function() {
             // Store current block if done
             if ( !singleLineComment( line ) && !insideMultiLineBlock ) {
                 if ( currentBlock ) {
-                    let type = _dss.getKeyType(_dss.trim(line));
-                    let key = _dss.getKey(_dss.trim(line), type);
+                    const lineToParse = endMultiLineComment(line) ? String(linesArr[index + 1]) : line;
+                    const type = _dss.getKeyType(_dss.trim(lineToParse));
+                    const key = _dss.getKey(_dss.trim(lineToParse), type);
 
                     _blocks.push( _dss.normalize( currentBlock ) );
                     _blockValues.push({

test/data/css/all-annotations.scss

@@ -0,0 +1,20 @@
+/**
+  * @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
+  * @markup <button>This is a button</button>
+  * @deprecated 123.321
+  * @deprecatedDescription This is deprecated.
+  * @group Buttons
+  * @type Color
+  * @subtype Text-Color
+  * @param {string} par1 - parmOne description
+  * @param {function} par2 - paramTwo description
+  * @param par3 - paramThree description
+  * @param par4
+  * @returns {number} - return description
+  * @returns - no type - return description
+  */

test/data/css/all-key-types.scss

@@ -0,0 +1,57 @@
+/**
+  * @name Button
+  * @description Button description
+  * @type myType
+  * @key myKey
+  */
+$button-bg: white;
+
+/**
+  * @name Grid
+  */
+$grid-bg: black;
+
+/**
+  * @name Spacing
+  */
+$spacing: (
+    0: 0,
+    1: 4px,
+    xl: 24px,
+    thin: 2px,
+    hair: 1px
+) !default;
+
+/**
+  * @name Decimal Round
+  */
+@function decimal-round($float, $digits: 2) {
+    $pow: pow(10, $digits);
+
+    @return round($float * $pow) / $pow;
+}
+
+/**
+  * @name k-d-flex
+  */
+.k-d-flex                   { display: flex; }
+
+/**
+  * @name k-resize-none
+  */
+
+/**
+  * @name Resize Both
+  * @type selector
+  * @key .k-resize-both
+  */
+
+$utils-resize: (
+    none,
+    both
+) !default;
+
+@each $resize in $utils-resize {
+    // sass-lint:disable-block no-important
+    .k-resize-#{$resize} { resize: $resize !important; }
+}

test/data/css/button.scss

@@ -0,0 +1,14 @@
+/**
+  * @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
+  *
+  * @markup
+  *   <span>
+  *     <button>This is a button</button>
+  *   </span>
+  */

test/data/css/description-with-special-symbol.scss

@@ -0,0 +1,5 @@
+/**
+  * @description Your standard description with an @ in it
+  * second row test
+  * @name Special character "@" description test.
+  */

test/data/css/markup-not-last.scss

@@ -0,0 +1,8 @@
+/**
+  * @name Button
+  * @markup
+  *   <span>
+  *     <button>This is a button</button>
+  *   </span>
+  * @description Your standard form button.
+  */

test/data/css/multi-line-description.scss

@@ -0,0 +1,5 @@
+/**
+  * @description Your standard form button.
+  * second row test
+  * @name Multi Line description
+  */

test/test.js

@@ -3,157 +3,161 @@ const dss = require('../dss');
 const fs = require('fs');
 const path = require('path');
 
-describe('Core tests', function() {
+[ 'css', 'scss' ].forEach((ext) => {
 
-    it('should should parse the data', function() {
-        const file = fs.readFileSync(path.join(__dirname, 'data/button.scss'), 'utf8');
+    describe(`Core tests - ${ext}`, function() {
 
-        dss.parse(file, {}, function(parsed) {
-            const data = parsed.blocks[0];
+        it('should should parse the data', function() {
+            const file = fs.readFileSync(path.join(__dirname, `data/${ext}/button.scss`), 'utf8');
 
-            assert.strictEqual(data.name, 'Button');
-            assert.strictEqual(data.description, 'Your standard form button.');
-            assert.strictEqual(data.state[0].name, ':hover');
-            assert.strictEqual(data.state[0].description, 'Highlights when hovering.');
-            assert.strictEqual(data.state[1].name, ':disabled');
-            assert.strictEqual(data.state[1].description, 'Dims the button when disabled.');
-            assert.strictEqual(data.state[2].name, '.primary');
-            assert.strictEqual(data.state[2].description, 'Indicates button is the primary action.');
-            assert.strictEqual(data.state[3].name, '.smaller');
-            assert.strictEqual(data.markup.example,
-                '   <span>\n' +
-                '     <button>This is a button</button>\n' +
-                '   </span>'
-            );
-            assert.strictEqual(data.markup.escaped,
-                '   &lt;span&gt;\n' +
-                '     &lt;button&gt;This is a button&lt;/button&gt;\n' +
-                '   &lt;/span&gt;'
-            );
+            dss.parse(file, {}, function(parsed) {
+                const data = parsed.blocks[0];
+
+                assert.strictEqual(data.name, 'Button');
+                assert.strictEqual(data.description, 'Your standard form button.');
+                assert.strictEqual(data.state[0].name, ':hover');
+                assert.strictEqual(data.state[0].description, 'Highlights when hovering.');
+                assert.strictEqual(data.state[1].name, ':disabled');
+                assert.strictEqual(data.state[1].description, 'Dims the button when disabled.');
+                assert.strictEqual(data.state[2].name, '.primary');
+                assert.strictEqual(data.state[2].description, 'Indicates button is the primary action.');
+                assert.strictEqual(data.state[3].name, '.smaller');
+                assert.strictEqual(data.markup.example,
+                    '   <span>\n' +
+                    '     <button>This is a button</button>\n' +
+                    '   </span>'
+                );
+                assert.strictEqual(data.markup.escaped,
+                    '   &lt;span&gt;\n' +
+                    '     &lt;button&gt;This is a button&lt;/button&gt;\n' +
+                    '   &lt;/span&gt;'
+                );
+            });
         });
-    });
 
-    it('multiline markup is correctly parsed when not as last parser', function() {
-        const file = fs.readFileSync(path.join(__dirname, 'data/markup-not-last.scss'), 'utf8');
+        it('multiline markup is correctly parsed when not as last parser', function() {
+            const file = fs.readFileSync(path.join(__dirname, `data/${ext}/markup-not-last.scss`), 'utf8');
 
-        dss.parse(file, {}, function(parsed) {
-            const data = parsed.blocks[0];
+            dss.parse(file, {}, function(parsed) {
+                const data = parsed.blocks[0];
 
-            assert.strictEqual(data.name, 'Button');
-            assert.strictEqual(data.description, 'Your standard form button.');
-            assert.strictEqual(data.markup.example,
-                '   <span>\n' +
-                '     <button>This is a button</button>\n' +
-                '   </span>'
-            );
-            assert.strictEqual(data.markup.escaped,
-                '   &lt;span&gt;\n' +
-                '     &lt;button&gt;This is a button&lt;/button&gt;\n' +
-                '   &lt;/span&gt;'
-            );
+                assert.strictEqual(data.name, 'Button');
+                assert.strictEqual(data.description, 'Your standard form button.');
+                assert.strictEqual(data.markup.example,
+                    '   <span>\n' +
+                    '     <button>This is a button</button>\n' +
+                    '   </span>'
+                );
+                assert.strictEqual(data.markup.escaped,
+                    '   &lt;span&gt;\n' +
+                    '     &lt;button&gt;This is a button&lt;/button&gt;\n' +
+                    '   &lt;/span&gt;'
+                );
+            });
         });
-    });
 
-    it('multiline description is correctly parsed', function() {
-        const file = fs.readFileSync(path.join(__dirname, 'data/multi-line-description.scss'), 'utf8');
+        it('multiline description is correctly parsed', function() {
+            const file = fs.readFileSync(path.join(__dirname, `data/${ext}/multi-line-description.scss`), 'utf8');
 
-        dss.parse(file, {}, function(parsed) {
-            const data = parsed.blocks[0];
+            dss.parse(file, {}, function(parsed) {
+                const data = parsed.blocks[0];
 
-            assert.strictEqual(data.name, 'Multi Line description');
-            assert.strictEqual(data.description, 'Your standard form button.\nsecond row test');
+                assert.strictEqual(data.name, 'Multi Line description');
+                assert.strictEqual(data.description, 'Your standard form button.\nsecond row test');
+            });
         });
-    });
 
-    it('description with the @ symbol is correctly parsed', function() {
-        const file = fs.readFileSync(path.join(__dirname, 'data/description-with-special-symbol.scss'), 'utf8');
+        it('description with the @ symbol is correctly parsed', function() {
+            const file = fs.readFileSync(path.join(__dirname, `data/${ext}/description-with-special-symbol.scss`), 'utf8');
 
-        dss.parse(file, {}, function(parsed) {
-            const data = parsed.blocks[0];
+            dss.parse(file, {}, function(parsed) {
+                const data = parsed.blocks[0];
 
-            assert.strictEqual(data.name, 'Special character "@" description test.');
-            assert.strictEqual(data.description, 'Your standard description with an @ in it\nsecond row test');
+                assert.strictEqual(data.name, 'Special character "@" description test.');
+                assert.strictEqual(data.description, 'Your standard description with an @ in it\nsecond row test');
+            });
         });
-    });
 
-    it('should should parse all annotations', function() {
-        const file = fs.readFileSync(path.join(__dirname, 'data/all-annotations.scss'), 'utf8');
+        it('should should parse all annotations', function() {
+            const file = fs.readFileSync(path.join(__dirname, `data/${ext}/all-annotations.scss`), 'utf8');
 
-        dss.parse(file, {}, function(parsed) {
-            const data = parsed.blocks[0];
+            dss.parse(file, {}, function(parsed) {
+                const data = parsed.blocks[0];
 
-            assert.strictEqual(data.name, 'Button');
-            assert.strictEqual(data.description, 'Your standard form button.');
-            assert.strictEqual(data.state[0].name, ':hover');
-            assert.strictEqual(data.state[0].description, 'Highlights when hovering.');
-            assert.strictEqual(data.state[1].name, ':disabled');
-            assert.strictEqual(data.state[1].description, 'Dims the button when disabled.');
-            assert.strictEqual(data.state[2].name, '.primary');
-            assert.strictEqual(data.state[2].description, 'Indicates button is the primary action.');
-            assert.strictEqual(data.state[3].name, '.smaller');
-            assert.strictEqual(data.markup.example, '<button>This is a button</button>');
-            assert.strictEqual(data.markup.escaped, '&lt;button&gt;This is a button&lt;/button&gt;');
-            assert.strictEqual(data.deprecated, '123.321');
-            assert.strictEqual(data.deprecatedDescription, 'This is deprecated.');
-            assert.strictEqual(data.group, 'buttons');
-            assert.strictEqual(data.type, 'color');
-            assert.strictEqual(data.subtype, 'text-color');
-            assert.strictEqual(data.param[0].type, '{string}');
-            assert.strictEqual(data.param[0].name, 'par1');
-            assert.strictEqual(data.param[0].description, 'parmOne description');
-            assert.strictEqual(data.param[1].type, '{function}');
-            assert.strictEqual(data.param[1].name, 'par2');
-            assert.strictEqual(data.param[1].description, 'paramTwo description');
-            assert.strictEqual(data.param[2].type, null);
-            assert.strictEqual(data.param[2].name, 'par3');
-            assert.strictEqual(data.param[2].description, 'paramThree description');
-            assert.strictEqual(data.param[3].type, null);
-            assert.strictEqual(data.param[3].name, 'par4');
-            assert.strictEqual(data.param[3].description, null);
-            assert.strictEqual(data.returns[0].type, '{number}');
-            assert.strictEqual(data.returns[0].name, null);
-            assert.strictEqual(data.returns[0].description, 'return description');
-            assert.strictEqual(data.returns[1].type, null);
-            assert.strictEqual(data.returns[1].name, null);
-            assert.strictEqual(data.returns[1].description, 'no type - return description');
+                assert.strictEqual(data.name, 'Button');
+                assert.strictEqual(data.description, 'Your standard form button.');
+                assert.strictEqual(data.state[0].name, ':hover');
+                assert.strictEqual(data.state[0].description, 'Highlights when hovering.');
+                assert.strictEqual(data.state[1].name, ':disabled');
+                assert.strictEqual(data.state[1].description, 'Dims the button when disabled.');
+                assert.strictEqual(data.state[2].name, '.primary');
+                assert.strictEqual(data.state[2].description, 'Indicates button is the primary action.');
+                assert.strictEqual(data.state[3].name, '.smaller');
+                assert.strictEqual(data.markup.example, '<button>This is a button</button>');
+                assert.strictEqual(data.markup.escaped, '&lt;button&gt;This is a button&lt;/button&gt;');
+                assert.strictEqual(data.deprecated, '123.321');
+                assert.strictEqual(data.deprecatedDescription, 'This is deprecated.');
+                assert.strictEqual(data.group, 'buttons');
+                assert.strictEqual(data.type, 'color');
+                assert.strictEqual(data.subtype, 'text-color');
+                assert.strictEqual(data.param[0].type, '{string}');
+                assert.strictEqual(data.param[0].name, 'par1');
+                assert.strictEqual(data.param[0].description, 'parmOne description');
+                assert.strictEqual(data.param[1].type, '{function}');
+                assert.strictEqual(data.param[1].name, 'par2');
+                assert.strictEqual(data.param[1].description, 'paramTwo description');
+                assert.strictEqual(data.param[2].type, null);
+                assert.strictEqual(data.param[2].name, 'par3');
+                assert.strictEqual(data.param[2].description, 'paramThree description');
+                assert.strictEqual(data.param[3].type, null);
+                assert.strictEqual(data.param[3].name, 'par4');
+                assert.strictEqual(data.param[3].description, null);
+                assert.strictEqual(data.returns[0].type, '{number}');
+                assert.strictEqual(data.returns[0].name, null);
+                assert.strictEqual(data.returns[0].description, 'return description');
+                assert.strictEqual(data.returns[1].type, null);
+                assert.strictEqual(data.returns[1].name, null);
+                assert.strictEqual(data.returns[1].description, 'no type - return description');
+            });
         });
-    });
 
-    it('should should parse and include key values', function() {
-        const file = fs.readFileSync(path.join(__dirname, 'data/all-key-types.scss'), 'utf8');
+        it('should should parse and include key values', function() {
+            const file = fs.readFileSync(path.join(__dirname, `data/${ext}/all-key-types.scss`), 'utf8');
 
-        dss.parse(file, {}, function(parsed) {
-            const blocks = parsed.blocks;
+            dss.parse(file, {}, function(parsed) {
+                const blocks = parsed.blocks;
 
-            assert.strictEqual(blocks[0].name, 'Button');
-            assert.strictEqual(blocks[0].description, 'Button description');
-            assert.strictEqual(blocks[0].type, 'mytype');
-            assert.strictEqual(blocks[0].key, 'myKey');
+                assert.strictEqual(blocks[0].name, 'Button');
+                assert.strictEqual(blocks[0].description, 'Button description');
+                assert.strictEqual(blocks[0].type, 'mytype');
+                assert.strictEqual(blocks[0].key, 'myKey');
 
-            assert.strictEqual(blocks[1].name, 'Grid');
-            assert.strictEqual(blocks[1].type, 'variable');
-            assert.strictEqual(blocks[1].key, '$grid-bg');
+                assert.strictEqual(blocks[1].name, 'Grid');
+                assert.strictEqual(blocks[1].type, 'variable');
+                assert.strictEqual(blocks[1].key, '$grid-bg');
 
-            assert.strictEqual(blocks[2].name, 'Spacing');
-            assert.strictEqual(blocks[2].type, 'variable');
-            assert.strictEqual(blocks[2].key, '$spacing');
+                assert.strictEqual(blocks[2].name, 'Spacing');
+                assert.strictEqual(blocks[2].type, 'variable');
+                assert.strictEqual(blocks[2].key, '$spacing');
 
-            assert.strictEqual(blocks[3].name, 'Decimal Round');
-            assert.strictEqual(blocks[3].type, 'function');
-            assert.strictEqual(blocks[3].key, 'decimal-round');
+                assert.strictEqual(blocks[3].name, 'Decimal Round');
+                assert.strictEqual(blocks[3].type, 'function');
+                assert.strictEqual(blocks[3].key, 'decimal-round');
 
-            assert.strictEqual(blocks[4].name, 'k-d-flex');
-            assert.strictEqual(blocks[4].type, 'selector');
-            assert.strictEqual(blocks[4].key, '.k-d-flex');
+                assert.strictEqual(blocks[4].name, 'k-d-flex');
+                assert.strictEqual(blocks[4].type, 'selector');
+                assert.strictEqual(blocks[4].key, '.k-d-flex');
 
-            assert.strictEqual(blocks[5].name, 'k-resize-none');
-            assert.strictEqual(blocks[5].type, null);
-            assert.strictEqual(blocks[5].key, null);
+                assert.strictEqual(blocks[5].name, 'k-resize-none');
+                assert.strictEqual(blocks[5].type, null);
+                assert.strictEqual(blocks[5].key, null);
 
-            assert.strictEqual(blocks[6].name, 'Resize Both');
-            assert.strictEqual(blocks[6].type, 'selector');
-            assert.strictEqual(blocks[6].key, '.k-resize-both');
+                assert.strictEqual(blocks[6].name, 'Resize Both');
+                assert.strictEqual(blocks[6].type, 'selector');
+                assert.strictEqual(blocks[6].key, '.k-resize-both');
+            });
         });
+
     });
 
 });