Merge pull request #535 from 0xProject/fix/commentRendering

Docs: Fix Type Comment Rendering

2 files changed, 46 insertions, 1 deletions

diff --git a/packages/react-docs/CHANGELOG.json b/packages/react-docs/CHANGELOG.json
index 951ed84e0..0b0d6bdc8 100644
--- a/packages/react-docs/CHANGELOG.json
+++ b/packages/react-docs/CHANGELOG.json
@@ -9,6 +9,10 @@
             {
                 "note": "Added support for rendering nested function types within interface types",
                 "pr": 519
+            },
+            {
+                "note": "Improve type comment rendering",
+                "pr": 535
             }
         ]
     },
diff --git a/packages/react-docs/src/components/type_definition.tsx b/packages/react-docs/src/components/type_definition.tsx
index 7a1c86da5..605b58fbd 100644
--- a/packages/react-docs/src/components/type_definition.tsx
+++ b/packages/react-docs/src/components/type_definition.tsx
@@ -122,7 +122,9 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef
                     </pre>
                 </div>
                 <div style={{ maxWidth: 620 }}>
-                    {customType.comment && <Comment comment={customType.comment} className="py2" />}
+                    {customType.comment && (
+                        <Comment comment={this._formatComment(customType.comment)} className="py2" />
+                    )}
                 </div>
             </div>
         );
@@ -132,4 +134,43 @@ export class TypeDefinition extends React.Component<TypeDefinitionProps, TypeDef
             shouldShowAnchor,
         });
     }
+    /**
+     * Type definition comments usually describe the type as a whole or the individual
+     * properties within the type. Since TypeDoc just treats these comments simply as
+     * one paragraph, we do some additional formatting so that we can display individual
+     * property comments on their own lines.
+     * E.g:
+     * Interface SomeConfig
+     * {
+     *   networkId: number,
+     *   derivationPath: string,
+     * }
+     * networkId: The ethereum networkId to set as the chainId from EIP155
+     * derivationPath: Initial derivation path to use e.g 44'/60'/0'
+     *
+     * Each property description should be on a new line.
+     */
+    private _formatComment(text: string) {
+        const NEW_LINE_REGEX = /(\r\n|\n|\r)/gm;
+        const sanitizedText = text.replace(NEW_LINE_REGEX, ' ');
+        const PROPERTY_DESCRIPTION_DIVIDER = ':';
+        if (!_.includes(sanitizedText, PROPERTY_DESCRIPTION_DIVIDER)) {
+            return sanitizedText;
+        }
+        const segments = sanitizedText.split(PROPERTY_DESCRIPTION_DIVIDER);
+        _.each(segments, (s: string, i: number) => {
+            if (i === 0) {
+                segments[i] = `**${s}**`;
+                return;
+            } else if (i === segments.length - 1) {
+                return;
+            }
+            const words = s.split(' ');
+            const property = words[words.length - 1];
+            words[words.length - 1] = `\n\n**${property}**`;
+            segments[i] = words.join(' ');
+        });
+        const final = segments.join(PROPERTY_DESCRIPTION_DIVIDER);
+        return final;
+    }
 }