@zx-libs/docgen v0.0.5

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

• @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.

• @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.

• @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 `/\.[mc]?[tj]sx?$/`.
  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

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.

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

OutputFileOptionLines

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

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.

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

License

MIT License © 2022-Present Capricorncd.