@zx-libs/docgen

v0.0.3

Published

6 hours ago

Some tool functions used in the Nodejs environment, It is mainly used to obtain the comment information in the code, and then output it as a Markdown file.

Downloads

0High
0Medium
0Low

capricorncd

@zx-libs/docgen node docgen node/docgen front-end

@zx-libs/docgen

A document generator that read the comments in the code and automatically generate MarkDown documents.

npm i -D @zx-libs/docgen

const { outputFile } = require('@zx-libs/docgen')
// import { outputFile } from '@zx-libs/docgen'

outputFile('./src', './outputDir/README.md', {})

see DEMO https://github.com/capricorncd/zx-libs/blob/main/node/docgen/scripts/docs.mjs

Methods

error(...args)

Output 😡 red color log in console

@returns void

getCommentsData(input, needArray, options)

Get comments from the input file or directory. Supported keywords are type, document, method, code and more.

For example

A source file ./src/index.js, or a directory ./src.

/**
 * @method someMethod(param)
 * someMethod description 1 ...
 * someMethod description 2 ...
 * @param param `any` param's description
 * @returns `object` return's description
 * @sort 192
 */
function someMethod(param) {
  // do something ...
  return {...};
}

Get comments info form ./src or ./src/index.js

nodejs file ./scripts/create-docs.js.

const path = require('path')
const { getCommentsData } = require('@zx-libs/docgen')

const result = getCommentsData(path.resolve(__dirname, './src'));
console.log(result);

result

{
  '/usr/.../src/index.js': {
    method_someMethod: {
      type: 'method',
      sort: 192,
      name: 'someMethod',
      fullName: 'someMethod(param)',
      desc: [
        'someMethod description 1 ...',
        'someMethod description 2 ...',
      ],
      params: [
        {
          name: 'param',
          required: true,
          desc: ['param\'s description'],
          types: ['any'],
          raw: 'param `any` param\'s description',
        },
      ],
      returns: [
        {
          types: ['object'],
          desc: ['return\'s description'],
          raw: '`object` return\'s description',
        },
      ],
      codes: [],
      private: false,
      path: '/usr/.../src/index.js',
    },
    method_someMethod2: { ... },
    document_someDocument: { ... },
    type_someTypeName: { ... },
    ...
  }
}

Parameter needArray is true, or const { data } = outputFile(path.resolve(__dirname, './src')), result/data:

[
  {
    type: 'method',
    sort: 192,
    name: 'someMethod',
    fullName: 'someMethod(param)',
    desc: [
      'someMethod description 1 ...',
      'someMethod description 2 ...',
    ],
    params: [
      {
        name: 'param',
        required: true,
        desc: ['param\'s description'],
        types: ['any'],
        raw: 'param `any` param\'s description',
      },
    ],
    returns: [
      {
        types: ['object'],
        desc: ['return\'s description'],
        raw: '`object` return\'s description',
      },
    ],
    codes: [],
    private: false,
    path: '/usr/.../src/index.js',
  },
  ...
]

Param|Types|Required|Description :--|:--|:--:|:-- input|string/string[]|yes|The target file or directory. needArray|boolean|no|It's true will be returned an array. default false. options|GetCommentsDataOptions|no|GetCommentsDataOptions, default {}

@returns Record<filePath, Record<commentTypeName, CommentInfoItem>> | CommentInfoItem[] It's an array if needArray is true. What's CommentInfoItem.

getTypes(data)

Get types from getCommentsData's returned data.

@returns CommentInfoItem[] Returned is only type CommentInfoItem.

isFileLike(filePath)

is file like, *.ext.

@returns boolean

isValidArray(arr)

Determine whether arr is an array and it has some elements.

Param|Types|Required|Description :--|:--|:--:|:-- arr|T[]|no|-

@generic T
@returns boolean

log(...args)

Output 😎 green color log in console

@returns void

mkdirSync(dir)

make a directory synchronously

@returns void

outputFile(input, outputDirOrFile, options)

Output the obtained annotation content as a document.

Param|Types|Required|Description :--|:--|:--:|:-- input|{[filePath]: {[key]: CommentInfoItem}}/CommentInfoItem[]/string|yes|Comment obtained from the source. When string it's a file path, and the getCommentsData will be called. What's CommentInfoItem. outputDirOrFile|string|no|Optional parameter. The file or directory where the output will be written. When outputDirOrFile is undefined, no file will be output. options|OutputFileOptions|no|OutputFileOptions

@returns OutputFileReturns | OutputFileReturns[] What's OutputFileReturns

toTableLines(data)

Convert data to a table in Markdown format.

@returns string[]

warn(...args)

Output 😕 yellow color log in console

@returns void

writeFileSync(outputFileName, outputLines)

Synchronized file write function.

@returns void

Types

CommentInfoItem

CommentInfoItem is the comment information read with the getCommentsData function.

interface CommentInfoItem {
  // method/type/class/document
  type: string
  // @method name(...args)'s `name`
  name: string
  // @method name(...args)'s `name(...args)`
  fullName: string
  // description
  desc: string[]
  // method's params
  params: CommentInfoItemParam[]
  // method's returns
  returns: CommentInfoItemReturn[]
  // for example codes
  codes: string[]
  // Whether the member method of the class is private
  private: boolean
  // file path
  path: string
  // [CommentInfoItemProp](#CommentInfoItemProp)
  props?: CommentInfoItemProp[]
  // sort in the output file
  sort: number
  // generic
  generics: string[]
}

CommentInfoItemParam

CommentInfoItem's params.

interface CommentInfoItemParam {
  // unprocessed raw string
  raw: string
  // parameter name or property name
  name: string
  // Whether the parameter is required, or the field must exist in the returned data.
  required: boolean
  // parameter or property's descriptions
  desc: string[]
  // parameter or property's types
  types: string[]
}

CommentInfoItemProp

The properties of CommentInfoItem, only exists when the type is type or interface.

interface CommentInfoItemProp extends CommentInfoItemParam {
  raw: string // raw annotation string
}

CommentInfoItemReturn

CommentInfoItem's return.

interface CommentInfoItemReturn {
  // returned's descriptions.
  desc: string[]
  // returned's types
  types: string[]
  // raw annotation string
  raw: string
}

DocTypes

type DocTypes = 'document' | 'method' | 'type' | 'constant'

ExpendTypesHandler

expend types handler of GetCommentsDataOptions

type ExpendTypesHandler = (data: CommentInfoItem, line: string) => void

GetCommentsDataOptions

Parameter options of function getCommentsData

interface GetCommentsDataOptions {
  // Regular expression for the type of file to be read, defaults to `/\.[tj]s$/`.
  fileType?: RegExp
  // Disables key sorting, defaults to `false`, and sorts alphabetically.
  disableKeySorting?: boolean
  // This `types` array is obtained from other files or directories for `extends` related processing.
  types?: CommentInfoItem[]
  // expend types of getCommentsData function.
  expendTypes?: string[]
  // handler of the expend types.
  expendTypesHandlers?: Record<string, ExpendTypesHandler>
  // Need to get source code of the type, default `['type', 'constant']`.
  codeTypes?: string[]
  // If true, the code in the comment will be added to the end of the @document or @method.
  isExtractCodeFromComments?: boolean
}

OutputFileInput

A parameter input of function outputFile.

type OutputFileInput =
  | string
  | string[]
  | Record<string, Record<string, CommentInfoItem>>
  | CommentInfoItem[]

OutputFileOptionAlias

Prop|Types|Required|Description :--|:--|:--:|:-- tableHead|Record<string, string>|no|Alias of table head th inner text. sourceCodeSummary|string|no|Summary of details, <details><summary>Source Code</summary></details>'s summary, default Source Code. requiredValues|OutputFileOptionAliasRequiredValues|no|Required values types|Record<string, string>|no|Alias of the DocTypes name. types: { method: '方法/函数' }

interface OutputFileOptionAlias {
  // Alias of table head th inner text.
  tableHead?: Record<string, string>
  // Summary of details, `<details><summary>Source Code</summary></details>`'s summary, default `Source Code`.
  sourceCodeSummary?: string
  // Required values
  requiredValues?: OutputFileOptionAliasRequiredValues
  // Alias of the DocTypes name. `types: { method: '方法/函数' }`
  types?: Record<string, string>
}

OutputFileOptionAliasRequiredValues

Required values of OutputFileOptionAlias. For example {requiredValues: {0: 'no', 1: 'yes'}} or {requiredValues: {method: {0: 'no', 1: 'yes'}}}. And {requiredValues: ['no', 'yes']} or {requiredValues: {method: ['no', 'yes']}}

type OutputFileOptionAliasRequiredValues =
  | Record<string, string>
  | Record<string, Record<string, string>>

OutputFileOptionHandler

Custom type output handler.

Prop|Types|Required|Description :--|:--|:--:|:-- arr|CommentInfoItem[],|yes|- options|OutputFileOptions,|yes|- lines|string[]|yes|-

type OutputFileOptionHandler = (
  arr: CommentInfoItem[],
  options: OutputFileOptions,
  lines: string[]
) => void

OutputFileOptionLines

Prop|Types|Required|Description :--|:--|:--:|:-- start|string/string[]|no|The start that need to be added at the start. end|string/string[]|no|The 'end' that need to be added at the end, such as adding some license information. ['## License', 'BLANK_LINE', 'MIT License © 2018-Present [Capricorncd](https://github.com/capricorncd).']. afterType|Record<string, string \| string[]>|no|It's will be appended to the [type], before the ## [other type] afterTitle|Record<string, string \| string[]>|no|It's will be insert after type title line. For example, {method: ['some type description content']}, It's will to insert after method line, like this's ['## Methods', 'some type description content', '...']

interface OutputFileOptionLines {
  // The `start` that need to be added at the start.
  start?: string | string[]
  // The 'end' that need to be added at the end, such as adding some license information. `['## License', 'BLANK_LINE', 'MIT License © 2018-Present [Capricorncd](https://github.com/capricorncd).']`.
  end?: string | string[]
  // It's will be appended to the `[type]`, before the `## [other type]`
  afterType?: Record<string, string | string[]>
  // It's will be insert after `type` title line.
  // For example, `{method: ['some type description content']}`,
  // It's will to insert after `method` line, like this's `['## Methods', 'some type description content', '...']`
  afterTitle?: Record<string, string | string[]>
}

OutputFileOptions

Options of the function outputFile, extends GetCommentsDataOptions

Prop|Types|Required|Description :--|:--|:--:|:-- fileType|RegExp|no|Regular expression for the type of file to be read, defaults to /\.[tj]s$/. disableKeySorting|boolean|no|Disables key sorting, defaults to false, and sorts alphabetically. types|CommentInfoItem[]|no|This types array is obtained from other files or directories for extends related processing. expendTypes|string[]|no|expend types of getCommentsData function. expendTypesHandlers|Record<string, ExpendTypesHandler>|no|handler of the expend types. codeTypes|string[]|no|Need to get source code of the type, default ['type', 'constant']. isExtractCodeFromComments|boolean|no|If true, the code in the comment will be added to the end of the @document or @method. methodWithRaw|boolean|no|Display methods using raw string, not table. default false typeWithTable|boolean|no|Display types using only table, not Source Code. default false typeWithSourceCode|boolean|no|Display types using only Source Code, not table. default false typeWithAuto|boolean|no|By default, table and <details><summary>Source Code</summary></details> are displayed, but sometimes table's data may not exist, only Source Code can be displayed and <details> not using. lines|OutputFileOptionLines|no|lines. OutputFileOptionLines alias|OutputFileOptionAlias|no|alias. OutputFileOptionAlias outputDocTypesAndOrder|string[]|no|Output types and their order, default ['document', 'method', 'type', 'constant'] handlers|Record<string, OutputFileOptionHandler>|no|Custom type output handler. Note that the default handler function will not be executed when this parameter is set. For example {method: (arr, options, lines) => do something}. tableAlign|Record<string, 'left' \| 'center' \| 'right'>|no|Alignment of table columns, {Required: 'center'}. Default {[key]: 'left'}

interface OutputFileOptions extends GetCommentsDataOptions {
  // Display `methods` using raw string, not table. default `false`
  methodWithRaw?: boolean
  // Display `types` using only table, not Source Code. default `false`
  typeWithTable?: boolean
  // Display `types` using only Source Code, not table. default `false`
  typeWithSourceCode?: boolean
  // By default, `table` and `<details><summary>Source Code</summary></details>` are displayed,
  // but sometimes `table`'s data may not exist, only `Source Code` can be displayed and `<details>` not using.
  typeWithAuto?: boolean
  // lines. [OutputFileOptionLines](#OutputFileOptionLines)
  lines?: OutputFileOptionLines
  // alias. [OutputFileOptionAlias](#OutputFileOptionAlias)
  alias?: OutputFileOptionAlias
  // Output types and their order, default `['document', 'method', 'type', 'constant']`
  outputDocTypesAndOrder?: string[]
  // Custom type output handler. Note that the default handler function will not be executed when this parameter is set. For example `{method: (arr, options, lines) => do something}`.
  handlers?: Record<string, OutputFileOptionHandler>
  // Alignment of table columns, {Required: 'center'}. Default `{[key]: 'left'}`
  tableAlign?: Record<string, 'left' | 'center' | 'right'>
}

OutputFileReturns

Returned data of function outputFile.

interface OutputFileReturns {
  // outputted filename
  outputFileName: string | null
  // line array in the output file
  lines: string[]
  // comments data read from code
  data: CommentInfoItem[]
}

TableHeadInnerText

Table head th inner text of the output file.

type TableHeadInnerText =
  | 'Name'
  | 'Param'
  | 'Prop'
  | 'Types'
  | 'Required'
  | 'Description'

ToTableLinesParamData

The options type of function toTableLines.

Prop|Types|Required|Description :--|:--|:--:|:-- align|string[]|yes|Alignment of the table content, left, center or right, the default is left. thead|string[]|no|The table header displays a one-dimensional array of content. {thead: ['Name', 'Description']}. tbody|string[][]|no|The table body displays a two-dimensional array of contents. {tbody: [['someName1', 'someDescription1'],['someName2', 'someDescription2']]}.

interface ToTableLinesParamData {
  // Alignment of the table content, `left`, `center` or `right`, the default is `left`.
  align: string[]
  // The table header displays a one-dimensional array of content.
  // `{thead: ['Name', 'Description']}`.
  thead?: string[]
  // The table body displays a two-dimensional array of contents.
  // `{tbody: [['someName1', 'someDescription1'],['someName2', 'someDescription2']]}`.
  tbody?: string[][]
}

Constants

BLANK_LINE

blank line.

const BLANK_LINE = ''

DOC_TYPES

Supported annotation types.

const DOC_TYPES = {
  method: 'method',
  type: 'type',
  document: 'document',
  constant: 'constant',
  property: 'property',
}

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@zx-libs/docgen

Methods

error(...args)

getCommentsData(input, needArray, options)

For example

getTypes(data)

isFileLike(filePath)

isValidArray(arr)

log(...args)

mkdirSync(dir)

outputFile(input, outputDirOrFile, options)

toTableLines(data)

warn(...args)

writeFileSync(outputFileName, outputLines)

Types

CommentInfoItem

CommentInfoItemParam

CommentInfoItemProp

CommentInfoItemReturn

DocTypes

ExpendTypesHandler

GetCommentsDataOptions

OutputFileInput

OutputFileOptionAlias

OutputFileOptionAliasRequiredValues

OutputFileOptionHandler

OutputFileOptionLines

OutputFileOptions

OutputFileReturns

TableHeadInnerText

ToTableLinesParamData

Constants

BLANK_LINE

DOC_TYPES

License