Merge pull request #1 from salesforce-ux/fix/comments

Ignore comments inside a code fence

Author: Brian Lonsdorf

lib/__tests__/__snapshots__/comments.js.snap

@@ -0,0 +1,38 @@
+exports[`test ignores annotations inside a code fence 1`] = `
+Array [
+  Object {
+    "annotations": Object {
+      "a": true,
+      "b": true,
+    },
+    "description": "This comment contains a code fence
+\`\`\`scss
+@media () {}
+\`\`\`",
+  },
+]
+`;
+
+exports[`test parses description and annotations (multi) 1`] = `
+Array [
+  Object {
+    "annotations": Object {
+      "a": "hello",
+      "b": "world",
+    },
+    "description": "This is a multi-line
+description",
+  },
+]
+`;
+
+exports[`test parses description and annotations 1`] = `
+Array [
+  Object {
+    "annotations": Object {
+      "world": true,
+    },
+    "description": "Hello",
+  },
+]
+`;

lib/__tests__/comments.js

@@ -0,0 +1,34 @@
+const comments = require('../comments')
+
+it('parses description and annotations', () => {
+  expect(comments(`
+    /**
+     * Hello
+     * @world
+     */
+  `)).toMatchSnapshot()
+})
+
+it('parses description and annotations (multi)', () => {
+  expect(comments(`
+    /**
+     * This is a multi-line
+     * description
+     * @a hello
+     * @b world
+     */
+  `)).toMatchSnapshot()
+})
+
+it('ignores annotations inside a code fence', () => {
+  expect(comments(`
+    /**
+     * This comment contains a code fence
+     * \`\`\`scss
+     * @media () {}
+     * \`\`\`
+     * @a
+     * @b
+     */
+  `)).toMatchSnapshot()
+})

lib/comments.js

@@ -25,14 +25,19 @@ const remove = pattern => s => s.replace(pattern, '')
  *
  */
 const reduceComment = (comment, line) => {
-  let match = line.match(/^@([^\s]+)(?:\s(.+))?/)
-  if (!match) {
+  let annotation = comment.get('__codeFence')
+    ? false
+    : line.match(/^@([^\s]+)(?:\s(.+))?/)
+  if (/```/.test(line)) {
+    comment = comment.set('__codeFence', !comment.get('__codeFence', false))
+  }
+  if (!annotation) {
     return comment.update('description', description =>
       description.push(line)
     )
   } else {
-    return comment.setIn(['annotations', match[1]],
-      _.isUndefined(match[2]) ? true : match[2]
+    return comment.setIn(['annotations', annotation[1]],
+      _.isUndefined(annotation[2]) ? true : annotation[2]
     )
   }
 }
@@ -51,6 +56,8 @@ module.exports = styles => {
     )
     .map(comment => comment
       .reduce(reduceComment, baseComment)
+      .update(comment =>
+        comment.keySeq().reduce((a, b) => /^__/.test(b) ? a.delete(b) : a, comment))
       .update(comment => comment
         .update('description', description =>
           description.join('\n').trim()