feat: add function return type to props table

ccontrols · Mar 26, 2020 · bc45094 · bc45094
1 parent ddba93e
commit bc45094
Show file tree

Hide file tree

Showing 4 changed files with 104 additions and 56 deletions.
diff --git a/core/specification/README.md b/core/specification/README.md
@@ -3,7 +3,7 @@
 -   [Overview](#overview)
 -   [Installation](#installation)
 -   [API](#api)
-    -   [MethodParameterType](#methodparametertype)
+    -   [run](#run)
 
 # Overview
 
@@ -23,16 +23,19 @@ $ npm install @component-controls/specification --save-dev
 
 <!-- START-TSDOC-TYPESCRIPT -->
 
-## MethodParameterType
+## run
 
-_defined in [@component-controls/specification/src/test.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/test.ts#L1)_
+run API to generate react-docgen-typescript props information tables.
 
+_defined in [@component-controls/specification/src/test.ts](https://github.com/ccontrols/component-controls/tree/master/core/specification/src/test.ts#L6)_
 
+**run**(`options`: undefined | string): number;
 
-### properties
+### parameters
 
-| Name    | Type   | Description |
-| ------- | ------ | ----------- |
-| `name*` | string |             |
+| Name      | Type                | Description                                             |
+| --------- | ------------------- | ------------------------------------------------------- |
+| `options` | undefined \| string | configuration options                                   |
+| `returns` | number              | a callable function of type PropsInfoExtractorFunction  |
 
 <!-- END-TSDOC-TYPESCRIPT -->
diff --git a/core/specification/src/test.ts b/core/specification/src/test.ts
@@ -1,3 +1,8 @@
-export interface MethodParameterType {
-  name: string;
-}
+/**
+ * run API to generate react-docgen-typescript props information tables.
+ * @param options configuration options
+ * @returns a callable function of type PropsInfoExtractorFunction
+ */
+export const run = (options?: string): number => {
+  return parseInt(options || '');
+};
diff --git a/core/specification/tmp-out-typedoc.json b/core/specification/tmp-out-typedoc.json
@@ -17,56 +17,77 @@
 			"children": [
 				{
 					"id": 2,
-					"name": "MethodParameterType",
-					"kind": 256,
-					"kindString": "Interface",
+					"name": "run",
+					"kind": 64,
+					"kindString": "Function",
 					"flags": {
-						"isExported": true
+						"isExported": true,
+						"isConst": true
 					},
-					"children": [
+					"comment": {
+						"shortText": "run API to generate react-docgen-typescript props information tables.",
+						"returns": "a callable function of type PropsInfoExtractorFunction\n"
+					},
+					"signatures": [
 						{
 							"id": 3,
-							"name": "name",
-							"kind": 1024,
-							"kindString": "Property",
+							"name": "run",
+							"kind": 4096,
+							"kindString": "Call signature",
 							"flags": {
 								"isExported": true
 							},
-							"sources": [
+							"comment": {
+								"shortText": "run API to generate react-docgen-typescript props information tables.",
+								"returns": "a callable function of type PropsInfoExtractorFunction\n"
+							},
+							"parameters": [
 								{
-									"fileName": "test.ts",
-									"line": 2,
-									"character": 6
+									"id": 4,
+									"name": "options",
+									"kind": 32768,
+									"kindString": "Parameter",
+									"flags": {
+										"isExported": true,
+										"isOptional": true
+									},
+									"comment": {
+										"shortText": "configuration options"
+									},
+									"type": {
+										"type": "union",
+										"types": [
+											{
+												"type": "intrinsic",
+												"name": "undefined"
+											},
+											{
+												"type": "intrinsic",
+												"name": "string"
+											}
+										]
+									}
 								}
 							],
 							"type": {
 								"type": "intrinsic",
-								"name": "string"
+								"name": "number"
 							}
 						}
 					],
-					"groups": [
-						{
-							"title": "Properties",
-							"kind": 1024,
-							"children": [
-								3
-							]
-						}
-					],
 					"sources": [
 						{
 							"fileName": "test.ts",
-							"line": 1,
-							"character": 36
+							"line": 6,
+							"character": 16
 						}
 					]
 				}
 			],
 			"groups": [
 				{
-					"title": "Interfaces",
-					"kind": 256,
+					"title": "Functions",
+					"kind": 64,
 					"children": [
 						2
 					]

diff --git a/scripts/tsdoc/extract-tsdoc.ts b/scripts/tsdoc/extract-tsdoc.ts
@@ -22,10 +22,25 @@ app.bootstrap({
 export const extractTSDoc = (files: string[], entries: string[]): Node[] | undefined => {
   const unresolvedTypeNames: string[] = [];
   const repoNames: { [key: string]: { repo?: string, filePath?: string, packageName?: string, relativePath?: string} } = {};
-  const pushPropTable = (nodes: Node[], title: string) => {
-    const result: Node[] = [];
+
+  const createPropsRpw = (name: string, isOptional: boolean, type: any, comment: string): NodeChildren => {
+    return { type : 'tableRow' , children: [
+      { type: 'tableCell', children: [ { type: 'inlineCode', value: `${name}${isOptional ? '': '*'}`}]},
+      {
+        type: 'tableCell',
+        children: type,
+      },
+      {
+        type: 'tableCell',
+        children: [{ type: 'text', value: comment }],
+      }
+    ]}
+  }
+  const extractPropTable = (nodes: Node[], title: string): { propsTable: Node[], table?: NodeChildren} => {
+    const propsTable: Node[] = [];
+    let table: NodeChildren | undefined;
     if (nodes) {
-      result.push({
+      propsTable.push({
         type: 'paragraph',
         children: [{
           type: 'heading',
@@ -36,7 +51,7 @@ export const extractTSDoc = (files: string[], entries: string[]): Node[] | undef
           }]
         }]  
       })
-      const table: NodeChildren = {
+      table = {
         type: 'table',
         children: [
           { type: 'tableRow', children: [
@@ -46,26 +61,21 @@ export const extractTSDoc = (files: string[], entries: string[]): Node[] | undef
           ]}
         ]
       }
-      result.push({
+      propsTable.push({
         type: 'paragraph',
         children: [table]
       });  
       nodes.forEach((child: any) => {
-        const tableRow: NodeChildren = { type : 'tableRow' , children: [
-          { type: 'tableCell', children: [ { type: 'inlineCode', value: `${child.name}${child.flags.isOptional ? '': '*'}`}]}
-        ]}
-        tableRow.children.push({
-          type: 'tableCell',
-          children: child.type ? extractPropType(child.type) : extractFunction(child, false),
-        });
-        tableRow.children.push({
-          type: 'tableCell',
-          children: [{ type: 'text', value: child.comment ? child.comment.shortText : ''}],
-        });
+        const tableRow: NodeChildren = createPropsRpw(
+          child.name,
+          child.flags.isOptional,
+          child.type ? extractPropType(child.type) : extractFunction(child, false),
+          child.comment ? child.comment.shortText : '');
+        //@ts-ignore
         table.children.push(tableRow);
       });  
-    }      
-    return result;
+    }
+    return { propsTable, table };
   }
   const extractFunction = (node: any, extractTable: boolean = true): Node[] => {
     const result: Node[] = [];
@@ -137,7 +147,15 @@ export const extractTSDoc = (files: string[], entries: string[]): Node[] | undef
           value: ';'
         })
         if (extractTable) {
-          result.push.apply(result, pushPropTable(signature.parameters, 'parameters'));
+          const { propsTable, table } = extractPropTable(signature.parameters, 'parameters');
+          if (table && signature.type) {
+            table.children.push(createPropsRpw(
+              'returns',
+              true,
+              extractPropType(signature.type),
+              signature.comment ? signature.comment.returns : ''))
+          }
+          result.push.apply(result, propsTable);
         }  
       }
       return result;
@@ -205,7 +223,8 @@ export const extractTSDoc = (files: string[], entries: string[]): Node[] | undef
         }
       });
     }
-    result.push.apply(result, pushPropTable(node.children || node.type, 'properties'));
+    const { propsTable } = extractPropTable(node.children || node.type, 'properties');
+    result.push.apply(result, propsTable);
     return result;
   }