jsdoc-parse-plus

jsdoc-parse-plus

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

Hello friend. Have you ever had the need to:

• ...parse standard and/or custom jsdoc tags into usable JavaScript objects?
• ...programmatically add, modify, or remove jsdoc tags?
• ...programmatically generate jsdoc comments from JavaScript data?

If you answered yes to any of those questions, then jsdoc-parse-plus is for you!

Version: 1.3.0

Summary of Utils

For detailed information on each util, see below this table.

function	Description
getCommentsFromFile	Extract all jsdoc comment strings from a file
getTag	Gets a jsdoc tag's data; if the tag type supports multiple entries, an array of the tags will be returned
parse	Parse a jsdoc comment string against all potential jsdoc tags and optional custom tags
parseTags	Parse a jsdoc comment string against specified tags only; custom tags may be included
removeTags	Removes a set of tags from jsdoc
toCommentString	Convert an object to a jsdoc comment string

---

Interfaces & Types

// 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 };

Using a custom linkRenderer

Some functions have an optional linkRenderer which is used to convert inline {@link} and {@tutorial} tags to clickable links.

If you do not specify linkRenderer, the internal linkRenderer will output a basic link:

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

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

However, you can override that by providing your own linkRenderer. For example, if you wanted to add a css class to your links, you would create a function like the following and pass that in as your linkRenderer:

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

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

It doesn't even have to be an anchor tag. Your custom function can return any string so you have the flexibility to do anything special that you might need.

Without further ado, the utils...

---

getCommentsFromFile

Extract all jsdoc comment strings from a file

Since v1.0.0

Param	Type	Default
file String contents of a file	string
config (optional) The configuration for output formatting	GetCommentsFromFileConfig	{ keepIndent = false }

Returns: {string[]} Array of jsdoc strings

Supporting Types

// 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

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

Examples

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 */',
]

---

getTag

Gets a jsdoc tag's data; if the tag type supports multiple entries, an array of the tags will be returned

Param	Type
jsdoc The entire jsdoc string	string
linkRenderer (optional) Optional function to override default rendering of inline link and tutorial tags	(link: InlineLink) => string

Returns: {(tag: string) => ITag | Array<ITag | ITag[]>} Function to get the tag or array of all tags that go by that name

For more information on linkRenderer, please see Using a custom linkRenderer.

Import

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

Examples

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',
  },
]

---

parse

Parse a jsdoc comment string against all potential jsdoc tags and optional custom tags

Since v1.0.0

Param	Type	Default
jsdoc The entire jsdoc comment string	string
customTags (optional) Optional array of custom tags parse	string[]	[]
linkRenderer (optional) Optional function to override default rendering of inline link and tutorial tags	(link: InlineLink) => string

Returns: {object} Object with keys of each parsed tag

For more information on linkRenderer, please see Using a custom linkRenderer.

Import

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

Examples

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',
    },
  ],
}

---

parseTags

Parse a jsdoc comment string against specified tags only; custom tags may be included

Since v1.0.0

Param	Type
jsdoc The entire jsdoc comment string	string
tags The tags to parse	string[]
linkRenderer (optional) Optional function to override default rendering of inline link and tutorial tags	(link: InlineLink) => string

Returns: {object} Object with keys of each parsed tag

For more information on linkRenderer, please see Using a custom linkRenderer.

Import

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

Examples

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',
    },
  ],
}

---

removeTags

Removes a set of tags from jsdoc

Param	Type
jsdoc The entire jsdoc string	string
tags Array of string tags to remove	string[]

Returns: {string} The jsdoc string the specified tags removed

Import

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

Examples

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
 */

---

toCommentString

Convert an object to a jsdoc comment string

Since v1.0.0

Param	Type	Default
tags Object containing keys of tags	{[tag: string]: ITag | Array<ITag | ITag[]>}
config (optional) The configuration for output formatting	ToCommentStringConfig	{ indentChars = 0 }

Returns: {string} The jsdoc string

Supporting Types

// 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

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

Examples

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
 */

---

Package Contents

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

License

MIT

Author

Michael Paravano

Dependencies

None

Changelog

[1.3.0] - 2021-01-03

• Added linkRenderer for custom renderings of {@link} and {@tutorial}