jsdoc-parse-plus

Parse, add, remove, or modify standard jsdoc tags or custom tags from comments; Generate jsdoc comments from JavaScript data.

// base tag type
export interface ITag {
  tag: string;
  value?: string;
  raw: string;
}

// for tags that can contain a description as part of their value (i.e. @param, @returns, etc)
export interface IDescriptive extends ITag {
  description?: string;
}

// additional keys for the @param tag type
export interface IParam extends IDescriptive {
  name: string;
  optional?: boolean;
  defaultValue?: string;
}

// for tags that contain a type (i.e. @param, @returns, etc)
export interface IType extends IDescriptive {
  type?: string;
}

// for inline link tags like {@link} and {@tutorial}
export type InlineLink = {
  tag: string,
  url: string,
  text: string,
  raw: string,
};

// util configuration types
export type GetCommentsFromFileConfig = { keepIndent?: boolean };
export type ToCommentStringConfig = { indentChars?: number };

const internalLinkRenderer = (link: InlineLink) => `<a href="${link.url}">${link.text}</a>

// outputs =>
<a href="url">text</a>

const myLinkRenderer = (link: InlineLink) => `<a class="css-class" href="${link.url}">${link.text}</a>

// outputs =>
<a class="css-class" href="url">text</a>

// The configuration type for the util:
//   keepIndent?: boolean = false - Whether or not to keep the indentation of the entire jsdoc comment block

export type GetCommentsFromFileConfig = { keepIndent?: boolean };

import { getCommentsFromFile, GetCommentsFromFileConfig } from 'jsdoc-parse-plus';

const file = `
/**
 * The first group
 * 
 * @since v1.0.0
 */asdf
asdf
/**
 * The second group
 * 
 * @since v1.0.0
 */
asdf
/** The third group */`;

getCommentsFromFile(file);

// outputs =>
[
  `/**
 * The first group
 * 
 * @since v1.0.0
 */`,
  `/**
 * The second group
 * 
 * @since v1.0.0
 */`,
  '/** The third group */',
]

import { getTag } from 'jsdoc-parse-plus';

const jsdoc = `
/**
 * The description goes here
 * 
 * @since v1.0.0 (modified v2.0.0)
 * @template T
 * @param {T} children - JSX children
 * @param {any[]} types - Types of children to match
 * @param {GetChildByTypeConfig} [{ customTypeKey: '__TYPE', prioritized: false }] - The configuration params
 * @param {string} [optionalParam='default text'] An optional param with a description without a dash
 * @returns {T} - The first matching child
 * @docgen_types
 * // Custom docgen tag
 * @example
 * // Examples...
 * getTag('@description')(jsdoc);
 * @customTag customTag value 1
 * @customTag customTag value 2
 */`;

const tag = getTag(jsdoc);

tag('@description');
// outputs =>
{ 
  tag: '@description', 
  value: 'The description goes here',
  raw: 'The description goes here',
}

tag('@param');
// outputs =>
[
  { 
    tag: '@param', 
    type: 'T',
    name: 'children',
    description: 'JSX children',
    optional: false,
    defaultValue: undefined,
    raw: '@param {T} children - JSX children',
  },
  { 
    tag: '@param', 
    type: 'any[]',
    name: 'types',
    description: 'Types of children to match',
    optional: false,
    defaultValue: undefined,
    raw: '@param {any[]} types - Types of children to match',
  },
  { 
    tag: '@param', 
    type: 'GetChildByTypeConfig',
    name: '{ customTypeKey: \'__TYPE\', prioritized: false }',
    description: 'The configuration params',
    optional: true,
    defaultValue: undefined,
    raw: '@param {GetChildByTypeConfig} [{ customTypeKey: \'__TYPE\', prioritized: false }] - The configuration params',
  },
  { 
    tag: '@param', 
    type: 'string',
    name: 'optionalParam',
    description: 'An optional param with a description without a dash',
    optional: true,
    defaultValue: '\'default text\'',
    raw: '@param {string} [optionalParam=\'default text\'] An optional param with a description without a dash',
  },
]

tag('@docgen_types');
// custom tag used once outputs =>
{ 
  tag: '@docgen_types', 
  value: '// Custom docgen tag',
  raw: '@docgen_types\n// Custom docgen tag',
}

tag('@customTag');
// custom tag used multiple times outputs =>
[
  { 
    tag: '@customTag', 
    value: 'customTag value 1',
    raw: '@customTag customTag value 1',
  },
  { 
    tag: '@customTag', 
    value: 'customTag value 2',
    raw: '@customTag customTag value 2',
  },
]

import { parse } from 'jsdoc-parse-plus';

const jsdoc = `
/**
 * The description goes here
 * 
 * @since v1.0.0 (modified v2.0.0)
 * @template T
 * @param {T} children - JSX children
 * @param {any[]} types - Types of children to match
 * @param {GetChildByTypeConfig} [{ customTypeKey: '__TYPE', prioritized: false }] - The configuration params
 * @param {string} [optionalParam='default text'] An optional param with a description without a dash
 * @returns {T} - The first matching child
 * @docgen_types
 * // Custom docgen tag
 * @example
 * // Examples...
 * getTag('@description')(jsdoc);
 * @customTag customTag value 1
 * @customTag customTag value 2
 * @see {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
 * Also, check out {@link http://www.google.com|Google} and
 * {@link https://github.com GitHub}.
 */`;

parse(jsdoc, ['customTag', 'docgen_types']);
// outputs =>
{ 
  description: {
    tag: '@description', 
    value: 'The description goes here',
    raw: 'The description goes here',
  },
  since: { 
    tag: '@since', 
    value: 'v1.0.0 (modified v2.0.0)',
    raw: '@since v1.0.0 (modified v2.0.0)',
  },
  template: [{ 
    tag: '@template',
    value: 'T',
    description: undefined,
    raw: '@template T',
  }],
  param: [
    { 
      tag: '@param', 
      type: 'T',
      name: 'children',
      description: 'JSX children',
      optional: false,
      defaultValue: undefined,
      raw: '@param {T} children - JSX children',
    },
    { 
      tag: '@param', 
      type: 'any[]',
      name: 'types',
      description: 'Types of children to match',
      optional: false,
      defaultValue: undefined,
      raw: '@param {any[]} types - Types of children to match',
    },
    { 
      tag: '@param', 
      type: 'GetChildByTypeConfig',
      name: '{ customTypeKey: \'__TYPE\', prioritized: false }',
      description: 'The configuration params',
      optional: true,
      defaultValue: undefined,
      raw: '@param {GetChildByTypeConfig} [{ customTypeKey: \'__TYPE\', prioritized: false }] - The configuration params',
    },
    { 
      tag: '@param', 
      type: 'string',
      name: 'optionalParam',
      description: 'An optional param with a description without a dash',
      optional: true,
      defaultValue: '\'default text\'',
      raw: '@param {string} [optionalParam=\'default text\'] An optional param with a description without a dash',
    },
  ],
  example: [{ 
    tag: '@example', 
    value: '// Examples...\ngetTag(\'@description\')(jsdoc);',
    raw: '@example\n// Examples...\ngetTag(\'@description\')(jsdoc);',
  }],
  returns: { 
    tag: '@returns', 
    type: 'T',
    description: 'The first matching child',
    raw: '@returns {T} - The first matching child',
  },
  see: [{ 
    tag: '@see', 
    value: '<a href="MyClass">MyClass</a> and <a href="MyClass#foo">MyClass\'s foo property</a>.\nAlso, check out <a href="http://www.google.com">Google</a> and\n<a href="https://github.com">GitHub</a>.',
    raw: '@see {@link MyClass} and [MyClass\'s foo property]{@link MyClass#foo}.\nAlso, check out {@link http://www.google.com|Google} and\n{@link https://github.com GitHub}.',
  }],
  docgen_types: { 
    tag: '@docgen_types', 
    value: '// Custom docgen tag',
    raw: '@docgen_types\n// Custom docgen tag',
  },
  customTag: [
    { 
      tag: '@customTag', 
      value: 'customTag value 1',
      raw: '@customTag customTag value 1',
    },
    { 
      tag: '@customTag', 
      value: 'customTag value 2',
      raw: '@customTag customTag value 2',
    },
  ],
}

import { parseTags } from 'jsdoc-parse-plus';

const jsdoc = `
/**
 * The description goes here
 * 
 * @since v1.0.0 (modified v2.0.0)
 * @template T
 * @param {T} children - JSX children
 * @param {any[]} types - Types of children to match
 * @param {GetChildByTypeConfig} [{ customTypeKey: '__TYPE', prioritized: false }] - The configuration params
 * @param {string} [optionalParam='default text'] An optional param with a description without a dash
 * @returns {T} - The first matching child
 * @docgen_types
 * // Custom docgen tag
 * @example
 * // Examples...
 * getTag('@description')(jsdoc);
 * @customTag customTag value 1
 * @customTag customTag value 2
 * @see {@link MyClass} and [MyClass's foo property]{@link MyClass#foo}.
 * Also, check out {@link http://www.google.com|Google} and
 * {@link https://github.com GitHub}.
 */`;

parseTags(jsdoc, ['@description', '@since', '@docgen_types', 'customTag', '@thisTagDoesntExist']);
// outputs =>
{ 
  description: {
    tag: '@description', 
    value: 'The description goes here',
    raw: 'The description goes here',
  },
  since: { 
    tag: '@since', 
    value: 'v1.0.0 (modified v2.0.0)',
    raw: '@since v1.0.0 (modified v2.0.0)',
  },
  docgen_types: { 
    tag: '@docgen_types', 
    value: '// Custom docgen tag',
    raw: '@docgen_types\n// Custom docgen tag',
  },
  customTag: [
    { 
      tag: '@customTag', 
      value: 'customTag value 1',
      raw: '@customTag customTag value 1',
    },
    { 
      tag: '@customTag', 
      value: 'customTag value 2',
      raw: '@customTag customTag value 2',
    },
  ],
}

import { removeTags } from 'jsdoc-parse-plus';

const jsdoc = `
/**
 * The description goes here
 * 
 * @since v1.0.0 (modified v2.0.0)
 * @template T
 * @param {T} children - JSX children
 * @param {any[]} types - Types of children to match
 * @param {GetChildByTypeConfig} [{ customTypeKey: '__TYPE', prioritized: false }] - The configuration params
 * @param {string} [optionalParam='default text'] An optional param with a description without a dash
 * @returns {T} - The first matching child
 */`;

removeTags(jsdoc, ['@description', '@template', '@param']);
// outputs =>
/**
 * @since v1.0.0 (modified v2.0.0)
 * @returns {T} - The first matching child
 */

// The configuration type for the util:
//   indentChars?: number = 0 - The number of characters that the output string should be indented

export type ToCommentStringConfig = { indentChars?: number };

import { toCommentString, ToCommentStringConfig } from 'jsdoc-parse-plus';

const tags = {
  description: { 
    tag: '@description', 
    value: 'The description goes here',
    raw: 'The description goes here',
  },
  since: { 
    tag: '@since', 
    value: 'v1.0.0',
    raw: '@since v1.0.0',
  },
};

toCommentString(tags);
// outputs =>
/**
 * The description goes here
 * @since v1.0.0
 */

Within the module you'll find the following directories and files:

package.json
CHANGELOG.md -- history of changes to the module
README.md -- this file
/lib
  └───/es5
    └───/getCommentsFromFile
      └───index.d.ts - 784 Bytes
      └───index.js - 2.29 KB
    └───/getTag
      └───index.d.ts - 768 Bytes
      └───index.js - 1.24 KB
      └───index.d.ts - 388 Bytes
      └───index.js - 1.22 KB
    └───/parse
      └───index.d.ts - 778 Bytes
      └───index.js - 1.74 KB
    └───/parseTags
      └───index.d.ts - 745 Bytes
      └───index.js - 1.03 KB
    └───/removeTags
      └───index.d.ts - 306 Bytes
      └───index.js - 1.58 KB
    └───/toCommentString
      └───index.d.ts - 825 Bytes
      └───index.js - 1.54 KB
    └───/types
      └───index.d.ts - 627 Bytes
      └───index.js - 79 Bytes
    └───/_private
      └───types.d.ts - 177 Bytes
      └───types.js - 79 Bytes
      └───utils.d.ts - 2.12 KB
      └───utils.js - 13.5 KB
  └───/es6
    └───/getCommentsFromFile
      └───index.d.ts - 784 Bytes
      └───index.js - 2.13 KB
    └───/getTag
      └───index.d.ts - 768 Bytes
      └───index.js - 1.12 KB
      └───index.d.ts - 388 Bytes
      └───index.js - 272 Bytes
    └───/parse
      └───index.d.ts - 778 Bytes
      └───index.js - 1.61 KB
    └───/parseTags
      └───index.d.ts - 745 Bytes
      └───index.js - 915 Bytes
    └───/removeTags
      └───index.d.ts - 306 Bytes
      └───index.js - 1.45 KB
    └───/toCommentString
      └───index.d.ts - 825 Bytes
      └───index.js - 1.39 KB
    └───/types
      └───index.d.ts - 627 Bytes
      └───index.js - 12 Bytes
    └───/_private
      └───types.d.ts - 177 Bytes
      └───types.js - 12 Bytes
      └───utils.d.ts - 2.12 KB
      └───utils.js - 11.97 KB

MIT

None