fix: account for multi-line comments in tokens, improve comment style

__tests__/common/formatHelpers/createPropertyFormatter.js

@@ -0,0 +1,80 @@
+/*
+ * Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with
+ * the License. A copy of the License is located at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+
+const createPropertyFormatter = require('../../../lib/common/formatHelpers/createPropertyFormatter');
+const createDictionary = require('../../../lib/utils/createDictionary');
+
+const properties = {
+  color: {
+    red: {
+      name: "color-red",
+      value: "#FF0000",
+      comment: "Foo bar qux",
+      attributes: {
+        category: "color",
+        type: "red",
+      },
+      path: [
+        "color",
+        "red",
+      ]
+    },
+    blue: {
+      name: "color-blue",
+      value: "#0000FF",
+      comment: "Foo\nbar\nqux",
+      attributes: {
+        category: "color",
+        type: "blue",
+      },
+      path: [
+        "color",
+        "blue",
+      ]
+    }
+  }
+};
+const dictionary = createDictionary({ properties });
+
+describe('common', () => {
+  describe('createPropertyFormatter', () => {
+    it(`should default to putting comment next to the output value`, () => {
+      // long commentStyle
+      const cssFormatter = createPropertyFormatter({ format: 'css', dictionary });
+      // short commentStyle
+      const sassFormatter = createPropertyFormatter({ format: 'sass', dictionary });
+
+      // red = single-line comment, blue = multi-line comment
+      const cssRed = cssFormatter(dictionary.tokens.color.red);
+      const cssBlue = cssFormatter(dictionary.tokens.color.blue);
+      const sassRed = sassFormatter(dictionary.tokens.color.red);
+      const sassBlue = sassFormatter(dictionary.tokens.color.blue);
+
+      // Note that since CSS puts it inside a selector, there is an indentation of 2 spaces as well
+      // CSS also has commentStyle long, whereas sass uses short
+      expect(cssRed).toEqual('  --color-red: #FF0000; /* Foo bar qux */');
+      expect(cssBlue).toEqual(`  /**
+   * Foo
+   * bar
+   * qux
+   */
+  --color-blue: #0000FF;`);
+
+      expect(sassRed).toEqual('$color-red: #FF0000; // Foo bar qux');
+      expect(sassBlue).toEqual(`// Foo
+// bar
+// qux
+$color-blue: #0000FF;`);
+    });
+  });
+});

lib/common/formatHelpers/createPropertyFormatter.js

@@ -19,6 +19,56 @@ const defaultFormatting = {
   suffix: ';'
 }
 
+/**
+ * Split a string comment by newlines and
+ * convert to multi-line comment if necessary
+ * @param {string} to_ret_prop
+ * @param {{comment: string; style: 'short' | 'long'; indentation: string}} options
+ * @param {'short' | 'long'} commentStyle
+ * @param {string} indentation
+ * @returns {{hasNewLines: boolean, comment: string}}
+ */
+function addComment(to_ret_prop, options) {
+  const { comment, style, indentation } = options;
+
+  const commentsByNewLine = comment.split("\n");
+  const hasNewLines = commentsByNewLine.length > 1;
+
+  const commentCase = `${style}${hasNewLines ? '-new-lines' :''}`;
+  let processed;
+
+  switch(commentCase) {
+    case 'short':
+      processed = `// ${comment}`;
+      break;
+    case 'long':
+      processed = `/* ${comment} */`;
+      break;
+    case 'short-new-lines':
+      processed = commentsByNewLine.reduce(
+        (acc, curr) => `${acc}${indentation}// ${curr}\n`,
+        ''
+      );
+      break;
+    case 'long-new-lines':
+      processed = commentsByNewLine.reduce(
+        (acc, curr) => `${acc}${indentation} * ${curr}\n`,
+        `${indentation}/**\n`
+      );
+      processed += `${indentation} */\n`;
+      break;
+  }
+
+  if (hasNewLines) {
+    // put the comment above the prop if it's multi-line
+    to_ret_prop = `${processed}${to_ret_prop}`;
+  } else {
+    to_ret_prop = `${to_ret_prop} ${processed}`;
+  }
+
+  return to_ret_prop;
+}
+
 /**
  * Creates a function that can be used to format a property. This can be useful
  * to use as the function on `dictionary.allTokens.map`. The formatting
@@ -152,11 +202,7 @@ function createPropertyFormatter({
     to_ret_prop += suffix;
 
     if (prop.comment && commentStyle !== 'none') {
-      if (commentStyle === 'short') {
-        to_ret_prop = to_ret_prop.concat(` // ${prop.comment}`);
-      } else {
-        to_ret_prop = to_ret_prop.concat(` /* ${prop.comment} */`);
-      }
+      to_ret_prop = addComment(to_ret_prop, { comment: prop.comment, style: commentStyle, indentation });
     }
 
     return to_ret_prop;