Fix JSDocs issues

Author: michaldudak

src/parser.ts

@@ -1,5 +1,6 @@
 import * as ts from 'typescript';
 import * as t from './types';
+import { Documentation } from './types/documentation';
 
 /**
  * Options that specify how the parser should act
@@ -295,24 +296,28 @@ export function parseFromProgram(
 			if (node.name === componentName) {
 				const usedProps: Set<string> = new Set();
 				// squash props
-				node.types.forEach((typeNode) => {
-					usedProps.add(typeNode.name);
+				node.props.forEach((propNode) => {
+					usedProps.add(propNode.name);
 
-					let { [typeNode.name]: currentTypeNode } = props;
+					let { [propNode.name]: currentTypeNode } = props;
 					if (currentTypeNode === undefined) {
-						currentTypeNode = typeNode;
-					} else if (currentTypeNode.$$id !== typeNode.$$id) {
+						currentTypeNode = propNode;
+					} else if (currentTypeNode.$$id !== propNode.$$id) {
 						currentTypeNode = t.propNode(
 							currentTypeNode.name,
-							currentTypeNode.jsDoc,
-							t.unionNode([currentTypeNode.propType, typeNode.propType]),
-							currentTypeNode.optional || typeNode.optional,
-							new Set(Array.from(currentTypeNode.filenames).concat(Array.from(typeNode.filenames))),
+							{
+								description: currentTypeNode.description,
+								defaultValue: currentTypeNode.defaultValue,
+								visibility: currentTypeNode.visibility,
+							},
+							t.unionNode([currentTypeNode.propType, propNode.propType]),
+							currentTypeNode.optional || propNode.optional,
+							new Set(Array.from(currentTypeNode.filenames).concat(Array.from(propNode.filenames))),
 							undefined,
 						);
 					}
 
-					props[typeNode.name] = currentTypeNode;
+					props[propNode.name] = currentTypeNode;
 				});
 
 				usedPropsPerSignature.push(usedProps);
@@ -337,6 +342,7 @@ export function parseFromProgram(
 					}
 					return propType;
 				}),
+				getDocumentation(symbol),
 				node.getSourceFile().fileName,
 			),
 		);
@@ -356,6 +362,7 @@ export function parseFromProgram(
 			t.componentNode(
 				name,
 				properties.map((x) => checkSymbol(x, new Set([(type as any).id]))),
+				getDocumentation(checker.getSymbolAtLocation(type.symbol?.valueDeclaration!)),
 				propsFilename,
 			),
 		);
@@ -460,9 +467,9 @@ export function parseFromProgram(
 		}
 
 		{
-			const typeNode = type as any;
+			const propNode = type as any;
 
-			const symbol = typeNode.aliasSymbol ? typeNode.aliasSymbol : typeNode.symbol;
+			const symbol = propNode.aliasSymbol ? propNode.aliasSymbol : propNode.symbol;
 			const typeName = symbol ? checker.getFullyQualifiedName(symbol) : null;
 			switch (typeName) {
 				case 'global.JSX.Element':
@@ -526,7 +533,7 @@ export function parseFromProgram(
 			if (type.isLiteral()) {
 				return t.literalNode(
 					type.isStringLiteral() ? `"${type.value}"` : type.value,
-					getDocumentation(type.symbol),
+					getDocumentation(type.symbol)?.description,
 				);
 			}
 			return t.literalNode(checker.typeToString(type));
@@ -607,7 +614,7 @@ export function parseFromProgram(
 		return t.simpleTypeNode('any');
 	}
 
-	function getDocumentation(symbol?: ts.Symbol): string | undefined {
+	function getDocumentation(symbol?: ts.Symbol): Documentation | undefined {
 		if (!symbol) {
 			return undefined;
 		}
@@ -619,17 +626,17 @@ export function parseFromProgram(
 			if (comments && comments.length === 1) {
 				const commentNode = comments[0];
 				if (ts.isJSDoc(commentNode)) {
-					if (Array.isArray(commentNode.comment)) {
-						return commentNode.comment.map((x) => x.text).join('\n');
-					}
-
-					return commentNode.comment as string | undefined;
+					return {
+						description: commentNode.comment as string | undefined,
+						defaultValue: commentNode.tags?.find((t) => t.tagName.text === 'default')?.comment,
+						visibility: getVisibilityFromJSDoc(commentNode),
+					};
 				}
 			}
 		}
 
 		const comment = ts.displayPartsToString(symbol.getDocumentationComment(checker));
-		return comment ? comment : undefined;
+		return comment ? { description: comment } : undefined;
 	}
 
 	function getSymbolFileNames(symbol: ts.Symbol): Set<string> {
@@ -642,3 +649,19 @@ export function parseFromProgram(
 function hasFlag(typeFlags: number, flag: number) {
 	return (typeFlags & flag) === flag;
 }
+
+function getVisibilityFromJSDoc(doc: ts.JSDoc): Documentation['visibility'] | undefined {
+	if (doc.tags?.some((tag) => tag.tagName.text === 'public')) {
+		return 'public';
+	}
+
+	if (doc.tags?.some((tag) => tag.tagName.text === 'internal')) {
+		return 'internal';
+	}
+
+	if (doc.tags?.some((tag) => tag.tagName.text === 'private')) {
+		return 'private';
+	}
+
+	return undefined;
+}

src/types/documentation.ts

@@ -0,0 +1,5 @@
+export interface Documentation {
+	description?: string;
+	defaultValue?: any;
+	visibility?: 'public' | 'private' | 'internal';
+}

src/types/nodes/baseNodes.ts

@@ -3,7 +3,3 @@ import { PropNode } from './prop';
 export interface Node {
 	type: string;
 }
-
-export interface DefinitionHolder extends Node {
-	types: PropNode[];
-}

src/types/nodes/component.ts

@@ -1,22 +1,29 @@
-import { Node, DefinitionHolder } from './baseNodes';
+import { Documentation } from '../documentation';
+import { Node } from './baseNodes';
 import { PropNode } from './prop';
 
 const typeString = 'ComponentNode';
 
-export interface ComponentNode extends DefinitionHolder {
+export interface ComponentNode extends Node {
 	name: string;
+	props: PropNode[];
 	propsFilename?: string;
+	description?: string;
+	visibility?: Documentation['visibility'];
 }
 
 export function componentNode(
 	name: string,
-	types: PropNode[],
+	props: PropNode[],
+	documentation: Documentation | undefined,
 	propsFilename: string | undefined,
 ): ComponentNode {
 	return {
 		type: typeString,
 		name: name,
-		types: types || [],
+		props: props || [],
+		description: documentation?.description,
+		visibility: documentation?.visibility,
 		propsFilename,
 	};
 }

src/types/nodes/prop.ts

@@ -1,10 +1,13 @@
+import { Documentation } from '../documentation';
 import { Node } from './baseNodes';
 
 const typeString = 'PropNode';
 
 export interface PropNode extends Node {
 	name: string;
-	jsDoc?: string;
+	description?: string;
+	defaultValue?: any;
+	visibility?: Documentation['visibility'];
 	propType: Node;
 	optional: boolean;
 	filenames: Set<string>;
@@ -16,7 +19,7 @@ export interface PropNode extends Node {
 
 export function propNode(
 	name: string,
-	jsDoc: string | undefined,
+	documentation: Documentation | undefined,
 	propType: Node,
 	optional: boolean,
 	filenames: Set<string>,
@@ -25,7 +28,9 @@ export function propNode(
 	return {
 		type: typeString,
 		name,
-		jsDoc,
+		description: documentation?.description,
+		defaultValue: documentation?.defaultValue,
+		visibility: documentation?.visibility,
 		propType,
 		optional,
 		filenames,

src/types/props/interface.ts

@@ -1,9 +1,11 @@
-import { Node, DefinitionHolder } from '../nodes/baseNodes';
+import { Node } from '../nodes/baseNodes';
 import { PropNode } from '../nodes/prop';
 
 const typeString = 'InterfaceNode';
 
-export interface InterfaceNode extends DefinitionHolder {}
+export interface InterfaceNode extends Node {
+	types: PropNode[];
+}
 
 export function interfaceNode(types?: PropNode[]): InterfaceNode {
 	return {

src/types/props/literal.ts

@@ -4,14 +4,14 @@ const typeString = 'LiteralNode';
 
 export interface LiteralNode extends Node {
 	value: unknown;
-	jsDoc?: string;
+	description?: string;
 }
 
-export function literalNode(value: unknown, jsDoc?: string): LiteralNode {
+export function literalNode(value: unknown, description?: string): LiteralNode {
 	return {
 		type: typeString,
 		value,
-		jsDoc,
+		description,
 	};
 }
 

test/callbacks/output.json

@@ -4,7 +4,7 @@
 		{
 			"type": "ComponentNode",
 			"name": "Component",
-			"types": [
+			"props": [
 				{
 					"type": "PropNode",
 					"name": "onChange",
@@ -66,4 +66,4 @@
 			]
 		}
 	]
-}
+}

test/jsdocs/input.tsx

@@ -0,0 +1,24 @@
+import * as React from 'react';
+
+/**
+ * The test component.
+ *
+ * @internal
+ */
+function Component(props: Props): React.ReactElement {
+	return <div {...props} />;
+}
+
+interface Props {
+	/**
+	 * The class name.
+	 * Used to make the component more classy.
+	 */
+	className?: string;
+	/**
+	 * A value.
+	 *
+	 * @default 10
+	 */
+	someValue?: number;
+}

test/jsdocs/output.json

@@ -0,0 +1,54 @@
+{
+	"type": "ProgramNode",
+	"body": [
+		{
+			"type": "ComponentNode",
+			"name": "Component",
+			"props": [
+				{
+					"type": "PropNode",
+					"name": "className",
+					"description": "The class name.\nUsed to make the component more classy.",
+					"propType": {
+						"type": "UnionNode",
+						"types": [
+							{
+								"type": "SimpleTypeNode",
+								"typeName": "undefined"
+							},
+							{
+								"type": "SimpleTypeNode",
+								"typeName": "string"
+							}
+						]
+					},
+					"optional": true,
+					"filenames": {}
+				},
+				{
+					"type": "PropNode",
+					"name": "someValue",
+					"description": "A value.",
+					"defaultValue": "10",
+					"propType": {
+						"type": "UnionNode",
+						"types": [
+							{
+								"type": "SimpleTypeNode",
+								"typeName": "undefined"
+							},
+							{
+								"type": "SimpleTypeNode",
+								"typeName": "number"
+							}
+						]
+					},
+					"optional": true,
+					"filenames": {}
+				}
+			],
+			"description": "The test component.",
+			"visibility": "internal"
+		}
+	]
+}