Document hook parameters

Author: michaldudak

src/parser.ts

@@ -423,6 +423,8 @@ export function parseFromProgram(
 		const type = checker.getTypeOfSymbolAtLocation(symbol, node);
 		const typeStack = new Set<number>([(type as any).id]);
 
+		const parameterDescriptions = getParameterDescriptionFromNode(node);
+
 		const checkedSignatures = type.getCallSignatures().map((signature) => {
 			return {
 				parameters: signature.parameters.map((param) => {
@@ -431,7 +433,14 @@ export function parseFromProgram(
 						typeStack,
 						param.getName(),
 					);
-					return t.parameterNode(type, param.getName(), getDocumentationFromSymbol(param));
+
+					const parameterDescription = parameterDescriptions[param.getName()];
+
+					return t.parameterNode(
+						type,
+						param.getName(),
+						parameterDescription ? { description: parameterDescription } : undefined,
+					);
 				}),
 
 				returnValue: checkType(signature.getReturnType(), typeStack, hookName),
@@ -762,3 +771,22 @@ function getVisibilityFromJSDoc(doc: ts.JSDoc): t.Documentation['visibility'] |
 
 	return undefined;
 }
+
+function getParameterDescriptionFromNode(node: ts.Node) {
+	const comments = ts.getJSDocCommentsAndTags(node);
+	if (comments && comments.length >= 1) {
+		const commentNode = comments[0];
+		if (ts.isJSDoc(commentNode)) {
+			const paramComments: Record<string, string> = {};
+			commentNode.tags?.forEach((tag) => {
+				if (ts.isJSDocParameterTag(tag) && typeof tag.comment === 'string') {
+					paramComments[tag.name.getText()] = tag.comment.replace(/^[\s-*:]+/g, '');
+				}
+			});
+
+			return paramComments;
+		}
+	}
+
+	return {};
+}

test/hook-multiple-parameters/input.ts

@@ -1,12 +1,16 @@
 /**
  * A hook defined as a function.
  *
+ * @param value - The value.
+ * @param onChange - The change handler.
+ * @param severity - The severity.
+ *
  * @internal
  */
 export function useHook(
 	value: string,
-	severity: Severity,
 	onChange: (newValue: string) => void,
+	severity: Severity = 'low',
 ): number {
 	return 42;
 }

test/hook-multiple-parameters/output.json

@@ -11,23 +11,9 @@
 					"type": {
 						"nodeType": "intrinsic",
 						"type": "string"
-					}
-				},
-				{
-					"nodeType": "parameter",
-					"name": "severity",
-					"type": {
-						"nodeType": "union",
-						"types": [
-							{
-								"nodeType": "literal",
-								"value": "\"low\""
-							},
-							{
-								"nodeType": "literal",
-								"value": "\"high\""
-							}
-						]
+					},
+					"documentation": {
+						"description": "The value."
 					}
 				},
 				{
@@ -49,6 +35,29 @@
 							"nodeType": "intrinsic",
 							"type": "void"
 						}
+					},
+					"documentation": {
+						"description": "The change handler."
+					}
+				},
+				{
+					"nodeType": "parameter",
+					"name": "severity",
+					"type": {
+						"nodeType": "union",
+						"types": [
+							{
+								"nodeType": "literal",
+								"value": "\"low\""
+							},
+							{
+								"nodeType": "literal",
+								"value": "\"high\""
+							}
+						]
+					},
+					"documentation": {
+						"description": "The severity."
 					}
 				}
 			],