From bc4509402aa59a881c99c27cb742ccf06d75eeb7 Mon Sep 17 00:00:00 2001 From: atanasster Date: Wed, 25 Mar 2020 21:52:33 -0400 Subject: [PATCH] feat: add function return type to props table --- core/specification/README.md | 17 +++--- core/specification/src/test.ts | 11 +++- core/specification/tmp-out-typedoc.json | 73 ++++++++++++++++--------- scripts/tsdoc/extract-tsdoc.ts | 59 +++++++++++++------- 4 files changed, 104 insertions(+), 56 deletions(-) diff --git a/core/specification/README.md b/core/specification/README.md index 0e9a9638a..22dcc28f7 100644 --- 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 -## 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 | diff --git a/core/specification/src/test.ts b/core/specification/src/test.ts index c0563daa1..5e5cc0526 100644 --- 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 index 74c784dce..cad59c711 100644 --- 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 index 1d0397281..feb846f34 100644 --- 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; }