@zx-libs/docgen
v0.0.5
Published
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
13
Maintainers
Readme
@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
Param|Types|Required|Description
:--|:--|:--:|:--
args|Array<string>
|yes|-
- @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 ifneedArray
is true. What's CommentInfoItem.
getTypes(data)
Get types from getCommentsData's returned data.
Param|Types|Required|Description
:--|:--|:--:|:--
data|Record<filePath, Record<commentTypeName, CommentInfoItem>>
/CommentInfoItem[]
|yes|The data obtained using the getCommentsData method
- @returns
CommentInfoItem[]
Returned is onlytype
CommentInfoItem.
isFileLike(filePath)
is file like, *.ext
.
Param|Types|Required|Description
:--|:--|:--:|:--
filePath|string
|yes|-
- @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
Param|Types|Required|Description
:--|:--|:--:|:--
args|Array<string>
|yes|-
- @returns
void
mkdirSync(dir)
make a directory synchronously
Param|Types|Required|Description
:--|:--|:--:|:--
dir|string
|yes|directory path
- @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.
Param|Types|Required|Description
:--|:--|:--:|:--
data|ToTableLinesParamData
|yes|see type ToTableLinesParamData.
- @returns
string[]
warn(...args)
Output 😕 yellow color log in console
Param|Types|Required|Description
:--|:--|:--:|:--
args|Array<string>
|yes|-
- @returns
void
writeFileSync(outputFileName, outputLines)
Synchronized file write function.
Param|Types|Required|Description
:--|:--|:--:|:--
outputFileName|string
|yes|Output filename, absolute path.
outputLines|string[]
/NodeJS.ArrayBufferView
/string
|yes|The output file content, an array of strings.
- @returns
void
Types
CommentInfoItem
CommentInfoItem is the comment information read with the getCommentsData function.
Prop|Types|Required|Description
:--|:--|:--:|:--
type|string
|yes|method/type/class/document
name|string
|yes|@method name(...args)'s name
fullName|string
|yes|@method name(...args)'s name(...args)
desc|string[]
|yes|description
params|CommentInfoItemParam[]
|yes|method's params
returns|CommentInfoItemReturn[]
|yes|method's returns
codes|string[]
|yes|for example codes
private|boolean
|yes|Whether the member method of the class is private
path|string
|yes|file path
props|CommentInfoItemProp[]
|no|CommentInfoItemProp
sort|number
|yes|sort in the output file
generics|string[]
|yes|generic
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
.
Prop|Types|Required|Description
:--|:--|:--:|:--
raw|string
|yes|unprocessed raw string
name|string
|yes|parameter name or property name
required|boolean
|yes|Whether the parameter is required, or the field must exist in the returned data.
desc|string[]
|yes|parameter or property's descriptions
types|string[]
|yes|parameter or property's types
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
.
Prop|Types|Required|Description
:--|:--|:--:|:--
name|string
|yes|parameter name or property name
required|boolean
|yes|Whether the parameter is required, or the field must exist in the returned data.
desc|string[]
|yes|parameter or property's descriptions
types|string[]
|yes|parameter or property's types
raw|string
|yes|raw annotation string
interface CommentInfoItemProp extends CommentInfoItemParam {
raw: string // raw annotation string
}
CommentInfoItemReturn
CommentInfoItem's return
.
Prop|Types|Required|Description
:--|:--|:--:|:--
desc|string[]
|yes|returned's descriptions.
types|string[]
|yes|returned's types
raw|string
|yes|raw annotation string
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
Prop|Types|Required|Description
:--|:--|:--:|:--
fileType|RegExp
|no|Regular expression for the type of file to be read, defaults to /\.[mc]?[tj]sx?$/
.
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.
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
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 /\.[mc]?[tj]sx?$/
.
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.
Prop|Types|Required|Description
:--|:--|:--:|:--
outputFileName|string
/null
|yes|outputted filename
lines|string[]
|yes|line array in the output file
data|CommentInfoItem[]
|yes|comments data read from code
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',
}
License
MIT License © 2022-Present Capricorncd.