feat: add @remarks and @privateRemarks

issue: #87
hosseinmd · Feb 18, 2021 · 40cbe4b · 40cbe4b
1 parent cb815f0
commit 40cbe4b
Show file tree

Hide file tree

Showing 5 changed files with 67 additions and 42 deletions.
diff --git a/src/parser.ts b/src/parser.ts
@@ -11,7 +11,6 @@ import { DESCRIPTION, PARAM } from "./tags";
 import {
   TAGS_DESCRIPTION_NEEDED,
   TAGS_GROUP,
-  TAGS_IS_CAMEL_CASE,
   TAGS_NAMELESS,
   TAGS_ORDER,
   TAGS_SYNONYMS,
@@ -246,6 +245,7 @@ function getIndentationWidth(
   return spaces + tabs * options.tabWidth;
 }
 
+const TAGS_ORDER_LOWER = TAGS_ORDER.map((tagOrder) => tagOrder.toLowerCase());
 /**
  * This will adjust the casing of tag titles, resolve synonyms, fix
  * incorrectly parsed tags, correct incorrectly assigned names and types, and
@@ -254,48 +254,55 @@ function getIndentationWidth(
  * @param parsed
  */
 function normalizeTags(parsed: Block): void {
-  parsed.tags.forEach((t) => {
-    t.tag = t.tag || "";
-    t.type = t.type || "";
-    t.name = t.name || "";
-    t.description = t.description || "";
-    t.default = t.default?.trim();
-
-    /** When the space between tag and type is missing */
-    const tagSticksToType = t.tag.indexOf("{");
-    if (tagSticksToType !== -1 && t.tag[t.tag.length - 1] === "}") {
-      t.type = t.tag.slice(tagSticksToType + 1, -1) + " " + t.type;
-      t.tag = t.tag.slice(0, tagSticksToType);
-    }
-
-    t.tag = t.tag.trim();
-    const lower = t.tag.toLowerCase();
-    if (
-      !TAGS_IS_CAMEL_CASE.includes(t.tag) &&
-      (TAGS_ORDER.includes(lower) || lower in TAGS_SYNONYMS)
-    ) {
-      t.tag = lower;
-    }
+  parsed.tags = parsed.tags.map(
+    ({ tag, type, name, description, default: _default, ...rest }) => {
+      tag = tag || "";
+      type = type || "";
+      name = name || "";
+      description = description || "";
+      _default = _default?.trim();
+
+      /** When the space between tag and type is missing */
+      const tagSticksToType = tag.indexOf("{");
+      if (tagSticksToType !== -1 && tag[tag.length - 1] === "}") {
+        type = tag.slice(tagSticksToType + 1, -1) + " " + type;
+        tag = tag.slice(0, tagSticksToType);
+      }
 
-    // resolve synonyms
-    if (t.tag in TAGS_SYNONYMS) {
-      t.tag = TAGS_SYNONYMS[t.tag as keyof typeof TAGS_SYNONYMS];
-    }
+      tag = tag.trim();
+      const lower = tag.toLowerCase();
+      const tagIndex = TAGS_ORDER_LOWER.indexOf(lower);
+      if (tagIndex >= 0) {
+        tag = TAGS_ORDER[tagIndex];
+      } else if (lower in TAGS_SYNONYMS) {
+        // resolve synonyms
+        tag = TAGS_SYNONYMS[lower as keyof typeof TAGS_SYNONYMS];
+      }
 
-    t.type = t.type.trim();
-    t.name = t.name.trim();
+      type = type.trim();
+      name = name.trim();
 
-    if (t.name && TAGS_NAMELESS.includes(t.tag)) {
-      t.description = `${t.name} ${t.description}`;
-      t.name = "";
-    }
-    if (t.type && TAGS_TYPELESS.includes(t.tag)) {
-      t.description = `{${t.type}} ${t.description}`;
-      t.type = "";
-    }
+      if (name && TAGS_NAMELESS.includes(tag)) {
+        description = `${name} ${description}`;
+        name = "";
+      }
+      if (type && TAGS_TYPELESS.includes(tag)) {
+        description = `{${type}} ${description}`;
+        type = "";
+      }
 
-    t.description = t.description.trim();
-  });
+      description = description.trim();
+
+      return {
+        tag,
+        type,
+        name,
+        description,
+        default: _default,
+        ...rest,
+      };
+    },
+  );
 }
 
 /**

diff --git a/src/roles.ts b/src/roles.ts
@@ -23,8 +23,10 @@ import {
   OVERRIDE,
   PARAM,
   PRIVATE,
+  PRIVATE_REMARKS,
   PROPERTY,
   PROVIDES_MODULE,
+  REMARKS,
   RETURNS,
   SEE,
   SINCE,
@@ -113,7 +115,6 @@ const TAGS_VERTICALLY_ALIGN_ABLE = [
   YIELDS,
 ];
 
-const TAGS_IS_CAMEL_CASE = [PROVIDES_MODULE];
 const TAGS_GROUP = [CALLBACK, TYPEDEF];
 
 const TAGS_ORDER = [
@@ -129,6 +130,8 @@ const TAGS_ORDER = [
   SINCE,
   CATEGORY,
   DESCRIPTION,
+  REMARKS,
+  PRIVATE_REMARKS,
   EXAMPLE,
   ABSTRACT,
   AUGMENTS,
@@ -157,7 +160,6 @@ const TAGS_ORDER = [
 
 export {
   TAGS_DESCRIPTION_NEEDED,
-  TAGS_IS_CAMEL_CASE,
   TAGS_NAMELESS,
   TAGS_GROUP,
   TAGS_ORDER,

diff --git a/src/tags.ts b/src/tags.ts
@@ -24,8 +24,10 @@ const MEMBEROF = "memberof";
 const OVERRIDE = "override";
 const PARAM = "param";
 const PRIVATE = "private";
+const PRIVATE_REMARKS = "privateRemarks";
 const PROPERTY = "property";
 const PROVIDES_MODULE = "providesModule";
+const REMARKS = "remarks";
 const RETURNS = "returns";
 const SEE = "see";
 const SINCE = "since";
@@ -71,9 +73,11 @@ export {
   MEMBEROF,
   OVERRIDE,
   PARAM,
+  PRIVATE_REMARKS,
   PRIVATE,
   PROPERTY,
   PROVIDES_MODULE,
+  REMARKS,
   RETURNS,
   SEE,
   SINCE,

diff --git a/tests/__snapshots__/objectProperty.test.js.snap b/tests/__snapshots__/objectProperty.test.js.snap
@@ -5,6 +5,11 @@ exports[`object property 1`] = `
  * @providesModule Foo
  * @providesModule bar
  * @flow
+ * @remarks This source code is licensed under the license found in the
+ *   LICENSE file in the root directory of this source tree.
+ * @privateRemarks This Source code is licensed under the license found in the
+ *   LICENSE file in the root directory of this source tree.
+ * @privateRemarks description
  */
 
 /**

diff --git a/tests/objectProperty.test.js b/tests/objectProperty.test.js
@@ -13,7 +13,14 @@ test("object property", () => {
   const result = subject(`
   /**
  * @providesModule Foo
- * @providesModule bar
+ * @remarks
+ * This source code is licensed under the license found in the LICENSE file in	
+ * the root directory of this source tree.	
+ * @privateRemarks This source code is licensed under the license found in the LICENSE file in	
+ * the root directory of this source tree.	
+ * @PrivaTeremaRks description 
+ * @providesmodule bar
+ * 
  * @flow
  */