Merge pull request #148 from docsbydoxdox/feature/jsdoc-parse-contents

[feat] Added a parseString method for parsing strings.

Author: neogeek

packages/doxdox-parser-jsdoc/.gitignore

@@ -1,5 +1,7 @@
 node_modules/
 
+cache/
+
 coverage/
 
 dist/

packages/doxdox-parser-jsdoc/package.json

@@ -10,7 +10,8 @@
   },
   "dependencies": {
     "jsdoc": "3.6.10",
-    "spawn-please": "1.0.0"
+    "spawn-please": "1.0.0",
+    "temp": "0.9.4"
   },
   "peerDependencies": {
     "doxdox-core": "4.0.0-preview.8"
@@ -23,6 +24,7 @@
   "devDependencies": {
     "@types/jest": "27.4.1",
     "@types/node": "17.0.21",
+    "@types/temp": "0.9.1",
     "jest": "27.5.1",
     "ts-jest": "27.1.3",
     "typescript": "4.5.5"

packages/doxdox-parser-jsdoc/src/index.test.ts

@@ -0,0 +1,89 @@
+import { parseString } from './index';
+
+describe('jsdoc parser', () => {
+    it('parse example jsdoc headers', async () => {
+        await expect(
+            parseString(
+                'lib/utils/index.js',
+                `/**
+ * Finds file in path.
+ *
+ *     console.log(await findFileInPath('./', 'package.json'));
+ *     console.log(await findFileInPath('../', 'package.json'));
+ *     console.log(await findFileInPath('~/git/github/doxdox/', '.package.json'));
+ *
+ * @param {string} [input] Directory to check for file.
+ * @param {string?} [fileName = 'package.json'] File name to check for.
+ * @return {Promise<string | null>} Path to package.json file.
+ * @public
+ */
+
+const findFileInPath = async (input, fileName = 'package.json') => {};
+
+/**
+ * Get the root directory of the package, supplied path or URL.
+ *
+ * @param {string?} [url] Optional path or URL.
+ * @return {string} Directory path.
+ * @public
+ */
+
+const getRootDirPath = (url) => {};`
+            )
+        ).resolves.toEqual(
+            expect.objectContaining({
+                path: 'lib/utils/index.js',
+                methods: expect.arrayContaining([
+                    expect.objectContaining({
+                        fullName: 'findFileInPath(input, fileName)',
+                        name: 'findFileInPath',
+                        params: expect.arrayContaining([
+                            expect.objectContaining({
+                                name: 'input',
+                                types: ['string']
+                            }),
+                            expect.objectContaining({
+                                name: 'fileName',
+                                types: ['string']
+                            })
+                        ]),
+                        private: false,
+                        returns: expect.arrayContaining([
+                            expect.objectContaining({
+                                name: undefined,
+                                types: ['Promise.<(string|null)>']
+                            })
+                        ]),
+                        slug: 'lib-utils-index-js-findfileinpath'
+                    }),
+                    expect.objectContaining({
+                        fullName: 'getRootDirPath(url)',
+                        name: 'getRootDirPath',
+                        params: expect.arrayContaining([
+                            expect.objectContaining({
+                                name: 'url',
+                                types: ['string']
+                            })
+                        ]),
+                        private: false,
+                        returns: expect.arrayContaining([
+                            expect.objectContaining({
+                                name: undefined,
+                                types: ['string']
+                            })
+                        ]),
+                        slug: 'lib-utils-index-js-getrootdirpath'
+                    })
+                ])
+            })
+        );
+    });
+    it('parse empty string', async () => {
+        await expect(parseString('test.js', '')).resolves.toEqual(
+            expect.objectContaining({
+                path: 'test.js',
+                methods: []
+            })
+        );
+    });
+});

packages/doxdox-parser-jsdoc/src/index.ts

@@ -1,16 +1,20 @@
+import { promises as fs } from 'fs';
+
 import { platform } from 'os';
 
 import { dirname, join } from 'path';
 
 import spawn from 'spawn-please';
 
+import temp from 'temp';
+
 import { findParentNodeModules, sanitizePath, slugify } from 'doxdox-core';
 
 import { File } from 'doxdox-core';
 
 import { Jsdoc } from './types';
 
-export default async (cwd: string, path: string): Promise<File> => {
+const parser = async (cwd: string, path: string): Promise<File> => {
     try {
         const nodeModulesDir = await findParentNodeModules(
             dirname(sanitizePath(import.meta.url))
@@ -93,3 +97,27 @@ export default async (cwd: string, path: string): Promise<File> => {
 
     return { path, methods: [] };
 };
+
+export const parseString = async (
+    path: string,
+    content: string,
+    cacheDir = './cache'
+): Promise<File> => {
+    temp.track();
+
+    const tempDir = await temp.mkdir({ prefix: 'doxdox-', dir: cacheDir });
+
+    const tempPath = join(tempDir, path);
+
+    await fs.mkdir(dirname(tempPath), { recursive: true });
+
+    await fs.writeFile(tempPath, content);
+
+    const file = await parser(tempDir, path);
+
+    await temp.cleanup();
+
+    return file;
+};
+
+export default parser;