docs: fix watch-mode and add more informations

Author: ph1p

documentation/.vuepress/config.js

@@ -11,10 +11,12 @@ module.exports = {
       require('../../dist/index.js').default,
       {
         folder: 'code',
-        jsDocConfigPath: './jsdoc.json',
-        source: './src',
+        source: './dist',
         dist: './documentation',
-        title: 'API'
+        title: 'API',
+        partials: ['./example/partials/*.hbs'],
+        readme: './README.md',
+        exclude: '**/*.d.ts,**/interfaces.*,**/constants.*,**/cmds.*'
       }
     ]
   ],

src/__tests__/utils.test.ts

@@ -1,4 +1,4 @@
-import { checkExtension, getExtension, getFilename, asyncForEach } from '../lib/utils';
+import { checkExtension, getExtension, getFilename } from '../lib/utils';
 
 describe('test utils', () => {
   test('getExtension should return true', () => {
@@ -19,16 +19,4 @@ describe('test utils', () => {
     // @ts-expect-error check empty method
     expect(getFilename()).toBe('');
   });
-  test('asyncForEach should run array async', async () => {
-    const promise1 = Promise.resolve(1);
-    const promise2 = Promise.resolve(2);
-
-    const results: number[] = [];
-
-    await asyncForEach([promise1, promise2], async result => {
-      results.push(await result);
-    });
-
-    expect(results).toEqual([1, 2]);
-  });
 });

src/index.ts

@@ -21,7 +21,7 @@ import { generateVueSidebar } from './lib/vue-sidebar';
 
 /**
  * Create the sidebar
- * @param options
+ * @param options {object}
  * @returns {Promise}
  */
 const createVuepressSidebar = options =>
@@ -37,8 +37,8 @@ const createVuepressSidebar = options =>
 
 /**
  * Parse file
- * @param file
- * @param argv
+ * @param file {DirectoryFile}
+ * @param argv {CLIArguments}
  * @returns {Promise}
  */
 const parseDirectoryFile = async (file: DirectoryFile, argv: CLIArguments) => {
@@ -83,7 +83,7 @@ const createReadmeFile = async (argv: CLIArguments, deletedPaths?: string[]) =>
 
 /**
  * Parse all CLI arguments
- * @param argv
+ * @param argv {CLIArguments}
  * @returns {object} all arguments
  */
 const parseArguments = (argv: CLIArguments) => {
@@ -187,6 +187,10 @@ export const generate = async (argv: CLIArguments) => {
   watchFiles(argv);
 };
 
+/**
+ * Watch files in source folder
+ * @param argv {CLIArguments}
+ */
 const watchFiles = (argv: CLIArguments) => {
   const { exclude, srcFolder, codeFolder, docsFolder, title } = parseArguments(argv);
 
@@ -230,8 +234,8 @@ const watchFiles = (argv: CLIArguments) => {
 
 /**
  * The vuepress plugins
- * @param argv
- * @param ctx
+ * @param argv {CLIArguments}
+ * @param ctx {object}
  * @returns {object}
  */
 const plugin = (argv: CLIArguments, ctx) => ({

src/lib/comment-parser.ts

@@ -10,7 +10,7 @@ import { DirectoryFile } from '../interfaces';
 
 /**
  * Search in file for @vuepress comment
- * @param fileContent
+ * @param fileContent {string} content of given file
  * @returns {object} object of found frontmatter data
  */
 export const parseComment = (fileContent: string) => {
@@ -45,9 +45,9 @@ export const parseComment = (fileContent: string) => {
 };
 
 /**
- * Helper function to get header as strctured markdown
- * @param content : ;
- * @param file
+ * Helper function to get header as structured markdown
+ * @param content {string} file content
+ * @param file {object} file object
  * @returns {string} markdown header
  */
 export const parseVuepressFileHeader = (content: string, file: DirectoryFile) => {

src/lib/list-folder.ts

@@ -12,10 +12,10 @@ import { DirectoryFile, FileTree } from '../interfaces';
 
 /**
  * Recursively traverse folders and return exluded files, a file list and a file tree.
- * @param srcPath
- * @param exclude
- * @param mainPath
- * @param tree
+ * @param srcPath {string} path to source dir
+ * @param exclude {array} exluded file patter list
+ * @param mainPath {string} path to hold source dir
+ * @param tree {object} tree array
  * @returns {object} paths array, tree, excluded array
  */
 export const listFolder = async (srcPath: string, exclude: string[] = [], mainPath?: string, tree: FileTree[] = []) => {

src/lib/parser.ts

@@ -18,11 +18,11 @@ import { parseVuepressFileHeader } from './comment-parser';
 
 /**
  * Parse a typescript or javascript file
- * @param file
- * @param srcFolder
- * @param destFolder
- * @param configPath
- * @param partials
+ * @param file {DirectoryFile}
+ * @param srcFolder {string}
+ * @param destFolder {string}
+ * @param configPath {string}
+ * @param partials {string | string[]}
  * @returns {object} file data
  */
 export const parseFile = async (
@@ -91,9 +91,9 @@ export const parseFile = async (
 
 /**
  * Parse a vue file
- * @param file
- * @param srcFolder
- * @param destFolder
+ * @param file {DirectoryFile}
+ * @param srcFolder {string}
+ * @param destFolder {string}
  * @returns {object} file data
  */
 export const parseVueFile = async (
@@ -153,9 +153,9 @@ export const parseVueFile = async (
 
 /**
  * Write content on disk
- * @param parseData
- * @param dest
- * @returns {object | null} null or type with some data of the saved file
+ * @param parseData {ParseReturn | null}
+ * @param dest {string}
+ * @returns {Promise | null} null or type with some data of the saved file
  */
 export const writeContentToFile = async (parseData: ParseReturn | null, dest: string) => {
   const root = process.cwd();

src/lib/utils.ts

@@ -6,40 +6,26 @@
  */
 /**
  * Get extension of file
- * @param path
+ * @param path {string}
  * @returns {string} extension of file
  */
 export const getExtension = (path: string) => path.substring(path.length, path.lastIndexOf('.'));
 
 /**
  * Check if extension ist correct
- * @param path
- * @param extensions
+ * @param path {string}
+ * @param extensions {string[]}
  * @returns {boolean}
  */
 export const checkExtension = (path: string, extensions: string[]) => extensions.indexOf(getExtension(path)) >= 0;
 
 /**
  * Get filename without extension
- * @param path
+ * @param path {string}
  * @returns {string} filename
  */
 export const getFilename = (path: string) =>
   path
     ?.split('/')
     ?.pop()
     ?.substring(0, path.lastIndexOf('.')) || '';
-
-/**
- * Async foreach loop
- * @param array
- * @callback callback
- */
-export const asyncForEach = async (
-  array: any[],
-  callback: (result: any, index: number, array: any[]) => Promise<void>
-) => {
-  for (let index = 0; index < array.length; index++) {
-    await callback(array[index], index, array);
-  }
-};

src/lib/vue-sidebar.ts

@@ -6,19 +6,17 @@
  */
 import fs from 'fs';
 import { join } from 'path';
-interface Node {
-  name: string;
-  children: any[];
-}
+
+import { FileTree } from '../interfaces';
 
 /**
  * Runs through the given tree structure and creates a vuepress config
  * @param data Informations to build config
- * @param data.fileTree tree strcture
- * @param data.codeFolder ./code/ folder
- * @param data.srcFolder ./src/ folder
- * @param data.docsFolder ./documentation/ folder
- * @param data.title title string
+ * @param data.fileTree {array} tree strcture
+ * @param data.codeFolder {string}./code/ folder
+ * @param data.srcFolder {string} ./src/ folder
+ * @param data.docsFolder {string} ./documentation/ folder
+ * @param data.title {string} title string
  * @returns {object} returns the vuepress menu strcture
  */
 export const generateVueSidebar = ({
@@ -35,9 +33,9 @@ export const generateVueSidebar = ({
   title: string;
 }) => {
   let rootFiles = [['', '::vuepress-jsdoc-title::']];
-  rootFiles = rootFiles.concat(fileTree.filter((file: Node) => !file.children).map((file: Node) => file.name));
+  rootFiles = rootFiles.concat(fileTree.filter((file: FileTree) => !file.children).map((file: FileTree) => file.name));
 
-  const rootFolder = fileTree.filter((file: Node) => file.children && file.children.length > 0);
+  const rootFolder = fileTree.filter((file: FileTree) => file.children && file.children.length > 0);
 
   const buildChildren = (children: any[], name: string, depth: number) => {
     let newChildren: any[] = [];
@@ -55,10 +53,10 @@ export const generateVueSidebar = ({
     return newChildren;
   };
 
-  const tree = rootFolder.map((folder: Node) => ({
+  const tree = rootFolder.map((folder: FileTree) => ({
     title: folder.name,
     collapsable: false,
-    children: buildChildren(folder.children, folder.name, 0)
+    children: buildChildren(folder.children!, folder.name, 0)
   }));
 
   return {