https://github.com/thespicymeatball/jsdoc-parse-plus

Parse, add, remove, or modify standard jsdoc tags or custom tags from comments; Generate jsdoc comments from JavaScript data.
https://github.com/thespicymeatball/jsdoc-parse-plus
documentation jsdoc jsdoc-comments parse
Last synced: 2 months ago
JSON representation
Parse, add, remove, or modify standard jsdoc tags or custom tags from comments; Generate jsdoc comments from JavaScript data.
Host: GitHub
URL: https://github.com/thespicymeatball/jsdoc-parse-plus
Owner: TheSpicyMeatball
License: mit
Created: 2020-12-24T17:28:15.000Z (over 4 years ago)
Default Branch: main
Last Pushed: 2021-01-04T03:22:06.000Z (over 4 years ago)
Last Synced: 2025-04-13T03:16:30.322Z (2 months ago)
Topics: documentation, jsdoc, jsdoc-comments, parse
Language: JavaScript
Homepage:
Size: 330 KB
Stars: 5
Watchers: 1
Forks: 1
Open Issues: 0
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project

README

        [![Build Status](https://travis-ci.com/TheSpicyMeatball/jsdoc-parse-plus.svg?branch=main)](https://travis-ci.com/TheSpicyMeatball/jsdoc-parse-plus)

[![Coverage Status](https://coveralls.io/repos/github/TheSpicyMeatball/jsdoc-parse-plus/badge.svg?branch=main)](https://coveralls.io/github/TheSpicyMeatball/jsdoc-parse-plus?branch=main)

[![dependencies Status](https://status.david-dm.org/gh/TheSpicyMeatball/jsdoc-parse-plus.svg)](https://david-dm.org/TheSpicyMeatball/jsdoc-parse-plus)

[![npm version](https://badge.fury.io/js/jsdoc-parse-plus.svg)](https://badge.fury.io/js/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

    

    

    getCommentsFromFileExtract all jsdoc comment strings from a filegetTagGets a jsdoc tag's data; if the tag type supports multiple entries, an array of the tags will be returnedparseParse a jsdoc comment string against all potential jsdoc tags and optional custom tagsparseTagsParse a jsdoc comment string against specified tags only; custom tags may be includedremoveTagsRemoves a set of tags from jsdoctoCommentStringConvert 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) => `${link.text}

// outputs =>

text

```



  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) => `${link.text}

// outputs =>

text

```

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

        TypeDefault

      

      
file
String contents of a filestringconfig (optional)The configuration for output formattingGetCommentsFromFileConfig{ 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 stringstringlinkRenderer (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

        TypeDefault

      

      
jsdoc
The entire jsdoc comment stringstringcustomTags (optional)
Optional array of custom tags parsestring[][]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: 'MyClass and MyClass\'s foo property.\nAlso, check out Google and\nGitHub.',

    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 stringstringtags
The tags to parsestring[]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 stringstringtagsArray of string tags to removestring[]

    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

        TypeDefault

      

      
tags
Object containing keys of tags{[tag: string]: ITag | Array<ITag | ITag[]>}config (optional)The configuration for output formattingToCommentStringConfig{ 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:

```html

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
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/thespicymeatball/jsdoc-parse-plus

Awesome Lists containing this project

README

Summary of Utils

Interfaces & Types

Using a custom linkRenderer

getCommentsFromFile

Supporting Types

Import

Examples

getTag

Import

Examples

parse

Import

Examples

parseTags

Import

Examples

removeTags

Import

Examples

toCommentString

Supporting Types

Import

Examples

Package Contents

License

Author

Dependencies
