WIP

Author: Gerard Brull

package-lock.json

@@ -37,6 +37,7 @@
     "clean-webpack-plugin": "^3.0.0",
     "clipboard-copy": "^3.1.0",
     "clsx": "^1.0.4",
+    "comment-parser": "^0.7.6",
     "common-dir": "^3.0.0",
     "copy-webpack-plugin": "^6.1.0",
     "core-js": "^3.6.4",
@@ -54,6 +55,7 @@
     "hash-sum": "^2.0.0",
     "is-directory": "^0.3.1",
     "javascript-stringify": "^2.0.0",
+    "jsdoc-parse": "^5.0.0",
     "jss": "^10.0.0",
     "jss-plugin-camel-case": "^10.0.0",
     "jss-plugin-compose": "^10.0.0",

package.json

@@ -5,7 +5,7 @@ import Markdown from 'rsg-components/Markdown';
 import Name from 'rsg-components/Name';
 import Type from 'rsg-components/Type';
 import Group from 'react-group';
-import doctrine from 'doctrine';
+import doctrine from 'comment-parser';
 import * as Rsg from '../../../typings';
 
 export const styles = ({ space }: Rsg.Theme) => ({

src/client/rsg-components/Argument/ArgumentRenderer.tsx

@@ -2,7 +2,8 @@ import path from 'path';
 import fs from 'fs';
 import { TagProps, TagParamObject, DocumentationObject, utils, TagObject } from 'react-docgen';
 import _ from 'lodash';
-import doctrine, { Annotation } from 'doctrine';
+import parse, { Tag } from 'comment-parser';
+
 import createLogger from 'glogg';
 import highlightCodeInMarkdown from './highlightCodeInMarkdown';
 import removeDoclets from './removeDoclets';
@@ -27,8 +28,20 @@ const JS_DOC_ALL_SYNONYMS: (keyof TagProps)[] = [
 // and https://github.com/styleguidist/react-styleguidist/issues/298
 const getDocletsObject = (str?: string) => ({ ...utils.docblock.getDoclets(str) });
 
-const getDoctrineTags = (documentation: Annotation) => {
-	return _.groupBy(documentation.tags, 'title');
+const getDoctrineTags = (documentation: parse.Comment) => {
+	console.log(documentation);
+	return _.groupBy(
+		documentation.tags
+			.filter((tag) => tag.tag !== 'return')
+			.reduce((acc, tag) => {
+				acc[tag.tag] = {
+					description: tag.description || null,
+					title: tag.tag,
+				};
+				return acc;
+			}, {}),
+		'title'
+	);
 };
 
 const doesExternalExampleFileExist = (componentPath: string, exampleFile: string) => {
@@ -59,41 +72,34 @@ export default function getProps(doc: DocumentationObject, filepath?: string): R
 	const outDocs: Rsg.TempPropsObject = { doclets: {}, displayName: '', ...doc, methods: undefined };
 
 	// Keep only public methods
-	outDocs.methods = (doc.methods || []).filter(method => {
+	outDocs.methods = (doc.methods || []).filter((method) => {
 		const doclets = method.docblock && utils.docblock.getDoclets(method.docblock);
 		return doclets && doclets.public;
 	}) as Rsg.MethodWithDocblock[];
 
 	// Parse the docblock of the remaining methods with doctrine to retrieve
 	// the JSDoc tags
 	// if a method is visible it must have a docblock
-	outDocs.methods = outDocs.methods.map(method => {
-		const allTags = getDoctrineTags(
-			doctrine.parse(method.docblock, { sloppy: true, unwrap: true })
-		);
+	outDocs.methods = outDocs.methods.map((method) => {
+		const allTags = getDoctrineTags(parse(`/** ${method.docblock} */`)[0]);
 
 		// Merge with react-docgen information about arguments and return value
 		// with information from JSDoc
 
-		const paramTags = getMergedTag(
-			allTags as TagProps,
-			JS_DOC_METHOD_PARAM_TAG_SYNONYMS
-		) as TagParamObject[];
+		const paramTags = getMergedTag(allTags, JS_DOC_METHOD_PARAM_TAG_SYNONYMS) as TagParamObject[];
 		const params =
 			method.params &&
-			method.params.map(param => ({
+			method.params.map((param) => ({
 				...param,
-				...paramTags.find(tagParam => tagParam.name === param.name),
+				...paramTags.find((tagParam) => tagParam.name === param.name),
 			}));
 
 		if (params) {
 			method.params = params;
 		}
 
-		const returnTags = getMergedTag(
-			allTags as TagProps,
-			JS_DOC_METHOD_RETURN_TAG_SYNONYMS
-		) as TagParamObject[];
+		const returnTags = getMergedTag(allTags, JS_DOC_METHOD_RETURN_TAG_SYNONYMS) as TagParamObject[];
+		console.log({ returnTags });
 		const returns = method.returns
 			? {
 					...method.returns,
@@ -102,7 +108,16 @@ export default function getProps(doc: DocumentationObject, filepath?: string): R
 						...method.returns.type,
 					},
 			  }
-			: returnTags[0];
+			: returnTags[0]
+			? {
+					description: returnTags[0].name,
+					title: returnTags[0].tag,
+					type: {
+						name: returnTags[0].type,
+						type: 'NameExpression',
+					},
+			  }
+			: undefined;
 
 		if (returns) {
 			method.returns = returns;
@@ -118,8 +133,8 @@ export default function getProps(doc: DocumentationObject, filepath?: string): R
 		// Read doclets from the description and remove them
 		outDocs.doclets = getDocletsObject(doc.description);
 
-		const documentation = doctrine.parse(doc.description);
-		outDocs.tags = getDoctrineTags(documentation) as TagProps;
+		const documentation = parse(doc.description);
+		outDocs.tags = getDoctrineTags(documentation[0]);
 
 		outDocs.description = highlightCodeInMarkdown(removeDoclets(doc.description));
 
@@ -142,19 +157,18 @@ export default function getProps(doc: DocumentationObject, filepath?: string): R
 
 	if (doc.props) {
 		// Read doclets of props
-		Object.keys(doc.props).forEach(propName => {
+		Object.keys(doc.props).forEach((propName) => {
 			if (!doc.props) {
 				return;
 			}
 			const prop = doc.props[propName];
 			const doclets = getDocletsObject(prop.description);
-
 			// When a prop is listed in defaultProps but not in props the prop.description is undefined
-			const documentation = doctrine.parse(prop.description || '');
+			const documentation = parse(`/** ${prop.description} */` || '');
 
 			// documentation.description is the description without tags
-			prop.description = documentation.description;
-			prop.tags = getDoctrineTags(documentation) as TagProps;
+			prop.description = documentation.length ? documentation[0].description : '';
+			prop.tags = getDoctrineTags(documentation[0]);
 
 			// Remove ignored props
 			if (doclets && doclets.ignore && outDocs.props) {