vitepress-jsdoc/dist/esm/parsers/jsdoc.js

A bridge between Vitepress and JSDoc-style commented codebases for hassle-free documentation.

import { join } from 'node:path';
import jsdoc2md from 'jsdoc-to-markdown';
import { readFileContent } from '../utilities/file-reader.js';
import { computePaths, getFileName, getFileFolder, } from '../utilities/file-path.js';
/**
 * The JsDocParser class provides functionality to parse files
 * and generate markdown content based on JSDoc comments.
 *
 * @implements {Parser}
 */
export class JsDocParser {
    /**
     * Parses the provided file and returns the generated markdown content.
     *
     * @param {DirectoryFile} file - The file to be parsed.
     * @param {ParserConfig} config - The configuration for parsing.
     * @returns {Promise<ParseReturn | undefined>} - The parsed content or undefined.
     */
    async parse(file, config) {
        const fileContent = await this.getFileContent(file);
        const markdownContent = await this.getMarkdownContent(file, config);
        const paths = this.getPaths(file, config);
        return {
            success: Boolean(markdownContent),
            file,
            empty: !markdownContent,
            content: fileContent + markdownContent,
            ...paths,
        };
    }
    /**
     * Retrieves the content of the provided file.
     *
     * @private
     * @param {DirectoryFile} file - The file whose content is to be retrieved.
     * @returns {Promise<string>} - The content of the file.
     */
    async getFileContent(file) {
        return readFileContent(file);
    }
    /**
     * Generates markdown content based on JSDoc comments in the provided file.
     *
     * @private
     * @param {DirectoryFile} file - The file to be parsed for JSDoc comments.
     * @param {ParserConfig} config - The configuration for parsing.
     * @returns {Promise<string>} - The generated markdown content.
     */
    async getMarkdownContent(file, config) {
        const relativePathSrc = getFileFolder(file);
        const { partialsPath, helpersPath } = this.getHandlebarsPaths(config);
        return jsdoc2md.render({
            'no-cache': Boolean(config.jsDocConfigPath),
            files: [
                join(process.cwd(), relativePathSrc, getFileName(file) + file.ext),
            ],
            configure: config.jsDocConfigPath,
            partial: partialsPath,
            helper: helpersPath,
        });
    }
    /**
     * Resolves the paths to handlebars partials and helpers.
     *
     * @private
     * @param {ParserConfig} config - The configuration containing paths.
     * @returns {Object} - An object containing paths to partials and helpers.
     */
    getHandlebarsPaths(config) {
        return {
            partialsPath: config.partials && config.partials.length > 0 ? config.partials : [],
            helpersPath: config.helpers && config.helpers.length > 0 ? config.helpers : [],
        };
    }
    /**
     * Computes the paths for the provided file based on the configuration.
     *
     * @private
     * @param {DirectoryFile} file - The file for which paths are to be computed.
     * @param {ParserConfig} config - The configuration for path computation.
     * @returns {Object} - An object containing the computed paths.
     */
    getPaths(file, config) {
        const { relativePathDest, folderInDest } = computePaths(file, config);
        const relativePathSrc = getFileFolder(file);
        return {
            relativePathDest,
            relativePathSrc,
            dest: folderInDest,
        };
    }
}
//# sourceMappingURL=jsdoc.js.map