api-docs-gen-api.md

api-docs-gen API References

Table Of Contents

• Interface
  • Config
  • ContentBuilder
  • ContentBuilderOptions
  • GenerateOptions
  • MarkdownContent
• Function
  • createContentBuilder
  • escapeText
  • escapeTextForTable
  • findCustomTags
  • generate
  • getDocSectionContent
  • getSafePathFromDisplayName
  • multiProcessor
  • multiResolver
  • tocProcessor
  • tocResolver
• Variable
  • DefaultConfig
• Enum
  • GenerateStyle
• TypeAlias
  • MarkdownProcessor
  • ReferenceResolver

Interface

Config

Configuration

Signature:

export interface Config 

Properties

linkReferencer

markdown link reference resolver

Signature:

linkReferencer?: ReferenceResolver;

processor

markdown docs processor

Signature:

processor: MarkdownProcessor;

ContentBuilder

Content Builder

Signature:

export interface ContentBuilder 

Methods

deindent

DeIndent content

Signature:

deindent(withoutNewLine?: boolean): void;

Parameters

Parameter	Type	Description
withoutNewLine	boolean	whether deindent to be added without new line

indent

Indent content

Signature:

indent(withoutNewLine?: boolean): void;

Parameters

Parameter	Type	Description
withoutNewLine	boolean

newline

Add line break

Signature:

newline(): void;

Parameters

Parameter	Type	Description

push

Add content

Signature:

push(content: string): void;

Parameters

Parameter	Type	Description
content	string	additional content

pushline

Add content with line break

Signature:

pushline(content: string): void;

Parameters

Parameter	Type	Description
content	string	additional content

Properties

content

Content

Signature:

readonly content: string;

indentLevel

Indent level

Signature:

readonly indentLevel: number;

ContentBuilderOptions

Content Builder options

Signature:

export interface ContentBuilderOptions 

Remarks

options that creating a ContentBuilder

Properties

indentLevel

Intdent level of Builder

Signature:

indentLevel?: number;

GenerateOptions

Generate Options for Generate API

Signature:

export interface GenerateOptions 

Properties

config

configration

Signature:

config: Config;

Remarks

see the Config

done

generate done callback

Signature:

done?: (pkgname: string, filename: string) => void;

Remarks

The callback that will be called when the generate process is finished.

errorOnTSDocConfig

TSDoc configration error callback

Signature:

errorOnTSDocConfig?: (error: string) => void;

Remarks

The callback occurs if you have an error in configration when --tsdoc-config is specified

style

generate style

Signature:

style: GenerateStyle;

Remarks

see the GenerateStyle

tsdocConfigPath

TSDoc configration path

Signature:

tsdocConfigPath?: string;

Remarks

Optional, see the here

MarkdownContent

Markdown content

Signature:

export interface MarkdownContent 

Properties

body

mkarkdown content

Signature:

body: string;

filename

markdown filename

Signature:

filename: string;

Function

createContentBuilder

Create a Content Builder

Signature:

export declare function createContentBuilder(options?: ContentBuilderOptions): ContentBuilder;

Parameters

Parameter	Type	Description
options	ContentBuilderOptions	Content Builder options

Returns

A ContentBuilder instance

escapeText

Escape text for markdown

Signature:

export declare function escapeText(text: string): string;

Parameters

Parameter	Type	Description
text	string	the target text

Returns

escaped text

escapeTextForTable

Escape text for markdown table

Signature:

export declare function escapeTextForTable(text: string): string;

Parameters

Parameter	Type	Description
text	string	the target text

Returns

escaped text

findCustomTags

Find custom tags

Signature:

export declare function findCustomTags(customBlocks: readonly DocBlock[], tag: string): DocBlock[];

Parameters

Parameter	Type	Description
customBlocks	readonly DocBlock[]	target cusotm blocks
tag	string	finding target tag

Returns

found custom blocks

Remarks

About custom tags, See the this issue

generate

Generate API docs

Signature:

export declare function generate(input: string[], output: string, options: GenerateOptions): Promise<void>;

Parameters

Parameter	Type	Description
input	string[]	input paths
output	string	output api docs full path
options	GenerateOptions	optiosn for generate, see the GenerateOptions

getDocSectionContent

Get DocSection content

Signature:

export declare function getDocSectionContent(model: ApiModel, pkg: ApiPackage, content: DocSection, contextItem: ApiItem, style: GenerateStyle, resolver: ReferenceResolver, customTags: string[]): string;

Parameters

Parameter	Type	Description
model	ApiModel	a model
pkg	ApiPackage	a package
content	DocSection	a content
contextItem	ApiItem	a context item
style	GenerateStyle	generate style, See the GenerateStyle
resolver	ReferenceResolver	resolver to resolve markdown content references
customTags	string[]

Returns

doc section markdown content

getSafePathFromDisplayName

Get safe path from display name of ApiItem

Signature:

export declare function getSafePathFromDisplayName(name: string): string;

Parameters

Parameter	Type	Description
name	string	the target displayname

Returns

safe path

multiProcessor

Process of API doc model

Signature:

export declare function process(model: ApiModel, pkg: ApiPackage, style: GenerateStyle, resolver: ReferenceResolver, customTags?: string[]): string | MarkdownContent[];

Parameters

Parameter	Type	Description
model	ApiModel	a model
pkg	ApiPackage	a package
style	GenerateStyle	generate style, See the GenerateStyle
resolver	ReferenceResolver	resolver to resolve markdown content references
customTags	string[]	TSDoc custom tags. This parameter is set to an array of custom tag names defined in --tsdoc-config.

Returns

markdown content strign or Array of MarkdownContent

Remarks

Generate the markdown contents the bellow:

- Function
- Enum
- Interface
- Class
- Variable
- TypeAlias

multiResolver

Resolve the markdown content reference

Signature:

export declare function resolve(style: GenerateStyle, item: ApiItem, model: ApiModel, pkg: ApiPackage, customTags?: string[]): string;

Parameters

Parameter	Type	Description
style	GenerateStyle	generate style, See the GenerateStyle
item	ApiItem	a item
model	ApiModel	a model
pkg	ApiPackage	a package
customTags	string[]	TSDoc custom tags. This parameter is set to an array of custom tag names defined in --tsdoc-config.

Returns

resolved the reference string

Remarks

This reference resolver is used by the processor to generate API docs references for separate pieces of markdown content.

tocProcessor

Process of API doc model

Signature:

export declare function process(model: ApiModel, pkg: ApiPackage, style: GenerateStyle, resolver: ReferenceResolver, customTags?: string[]): string | MarkdownContent[];

Parameters

Parameter	Type	Description
model	ApiModel	a model
pkg	ApiPackage	a package
style	GenerateStyle	generate style, See the GenerateStyle
resolver	ReferenceResolver	resolver to resolve markdown content references
customTags	string[]	TSDoc custom tags. This parameter is set to an array of custom tag names defined in --tsdoc-config.

Returns

markdown string content that have TOC

Remarks

Generate the markdown contents that have TOC. About API doc model, see the doc model structure, and doc model API. In about generate api docs, see the api-docs-gen API References

tocResolver

Resolve the markdown content reference

Signature:

export declare function resolve(style: GenerateStyle, item: ApiItem, model: ApiModel, pkg: ApiPackage, customTags?: string[]): string;

Parameters

Parameter	Type	Description
style	GenerateStyle	generate style, See the GenerateStyle
item	ApiItem	a item
model	ApiModel	a model
pkg	ApiPackage	a package
customTags	string[]	TSDoc custom tags. This parameter is set to an array of custom tag names defined in --tsdoc-config.

Returns

resolved the reference string

Remarks

This reference resolver is used by the processor to generate a reference specifically for API docs of markdown content with TOC.

Variable

DefaultConfig

Default Configration

Signature:

DefaultConfig: Config

Remarks

Default config for the CLI

Enum

GenerateStyle

The generate style

Signature:

export declare const enum GenerateStyle 

Members

Member	Value	Description
Directory	"directory"	Output api docs files for each package
NoPrefix	"noprefix"	No Prefix the output api docs file name
Prefix	"prefix"	Prefix the output api docs file name with package name

Remarks

The value of this constants is the same as that taken from --genereate-style option.

TypeAlias

MarkdownProcessor

Markdown docs processor

Signature:

export declare type MarkdownProcessor = (model: ApiModel, pkg: ApiPackage, style: GenerateStyle, resolver: ReferenceResolver, customTags?: string[]) => string | MarkdownContent[];

ReferenceResolver

Markdown reference resolver

Signature:

export declare type ReferenceResolver = (style: GenerateStyle, item: ApiItem, model: ApiModel, pkg: ApiPackage, customTags?: string[]) => string;