feat: support custom tags (#31)

* feat: support custom tags

* docs: update api docs

* test: update

Author: kazupon

.eslintrc.js

@@ -26,6 +26,7 @@ module.exports = {
     '@typescript-eslint/member-delimiter-style': 'off',
     '@typescript-eslint/no-use-before-define': 'off',
     '@typescript-eslint/explicit-module-boundary-types': 'off',
-    '@typescript-eslint/ban-ts-comment': 'off'
+    '@typescript-eslint/ban-ts-comment': 'off',
+    '@typescript-eslint/no-non-null-assertion': 'off'
   }
 }

README.md

@@ -33,11 +33,12 @@ Usage
   $ api-docs-gen <package1.api.json> <package2.api.json> ...
 
 Options
-  --config, -c              configuration file
+  --config, -c              configration file
   --output, -o              output dierectory that is markdown contents
   --generate-style, -g      document generating style, default 'prefix'
                             'prefix': be able to separated with each package name
                             'directory': be able to separated with each package directory
+  --tsdoc-config, -t        tsdoc configration file
 ```
 
 
@@ -53,7 +54,7 @@ const input = [path.resolve(process.cwd(), './package1.api.json')]
 const output = path.resolve(process.cwd(), './docs')
 
 // generate API docs with prefixed package name
-await generate(input, output, 'prefix', DefaultConfig)
+await generate(input, output, { style: 'prefix', config: DefaultConfig })
 ```
 
 About details, See the [API References](https://github.com/kazupon/api-docs-gen/blob/master/api-docs-gen-api.md)
@@ -76,6 +77,21 @@ $ yarn example:gen # genearte API docs with `api-docs-gen`
 $ yarn example:docs # run vuepress
 ```
 
+## :bookmark: TSDoc custom tags
+
+`api-docs-gen` allows TSDoc custom tags to be processed using [tsdoc-config](https://github.com/microsoft/tsdoc/tree/master/tsdoc-config).
+
+You can make it work from the `api-extractor` model by specifying tsdoc configration in the `--tsdoc-config` option as follows:
+
+```bash
+$ api-docs-gen package1.api.json --tsdoc-config ./tsdoc.json
+```
+
+If you want to output custom tags comment to markdown, you need to implement and configure the custom `MarkdownProcessor`.
+
+For the `MarkdownProcessor`, see the [API References](https://github.com/kazupon/api-docs-gen/blob/master/api-docs-gen-api.md).
+
+See how to configure it in the following configration.
 
 ## :wrench: Configration
 You can fully customize the generation of api docs using the config offered by `api-docs-gen`.

api-docs-gen-api.md

@@ -6,6 +6,7 @@
   - [Config](#config)
   - [ContentBuilder](#contentbuilder)
   - [ContentBuilderOptions](#contentbuilderoptions)
+  - [GenerateOptions](#generateoptions)
   - [MarkdownContent](#markdowncontent)
 - [Function](#function)
   - [createContentBuilder](#createcontentbuilder)
@@ -199,6 +200,87 @@ indentLevel?: number;
 ```
 
 
+### GenerateOptions
+
+Generate Options for Generate API
+
+**Signature:**
+```typescript
+export interface GenerateOptions 
+```
+
+
+#### Methods
+
+
+#### Properties
+
+##### config
+
+configration
+
+**Signature:**
+```typescript
+config: Config;
+```
+
+#### Remarks
+
+see the [Config](#config)
+
+##### done
+
+generate done callback
+
+**Signature:**
+```typescript
+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:**
+```typescript
+errorOnTSDocConfig?: (error: string) => void;
+```
+
+#### Remarks
+
+The callback occurs if you have an error in configration when `--tsdoc-config` is specified
+
+##### style
+
+generate style
+
+**Signature:**
+```typescript
+style: GenerateStyle;
+```
+
+#### Remarks
+
+see the [GenerateStyle](#generatestyle)
+
+##### tsdocConfigPath
+
+TSDoc configration path
+
+**Signature:**
+```typescript
+tsdocConfigPath?: string;
+```
+
+#### Remarks
+
+Optional, see the [here](https://github.com/microsoft/tsdoc/tree/master/tsdoc-config)
+
+
 ### MarkdownContent
 
 Markdown content
@@ -304,7 +386,7 @@ Generate API docs
 
 **Signature:**
 ```typescript
-export declare function generate(input: string[], output: string, style: GenerateStyle, config: Config, callback?: (pkgname: string, filename: string) => void): Promise<void>;
+export declare function generate(input: string[], output: string, options: GenerateOptions): Promise<void>;
 ```
 
 #### Parameters
@@ -313,17 +395,15 @@ export declare function generate(input: string[], output: string, style: Generat
 | --- | --- | --- |
 | input | string\[\] | input paths |
 | output | string | output api docs full path |
-| style | GenerateStyle | generate style, see the [GenerateStyle](#generatestyle) |
-| config | Config | configration, see the [Config](#config) |
-| callback | (pkgname: string, filename: string) =&gt; void |  |
+| options | GenerateOptions | optiosn for generate, see the [GenerateOptions](#generateoptions) |
 
 ### getDocSectionContent
 
 Get DocSection content
 
 **Signature:**
 ```typescript
-export declare function getDocSectionContent(model: ApiModel, pkg: ApiPackage, content: DocSection, contextItem: ApiItem, style: GenerateStyle, resolver: ReferenceResolver): string;
+export declare function getDocSectionContent(model: ApiModel, pkg: ApiPackage, content: DocSection, contextItem: ApiItem, style: GenerateStyle, resolver: ReferenceResolver, customTags: string[]): string;
 ```
 
 #### Parameters
@@ -336,6 +416,7 @@ export declare function getDocSectionContent(model: ApiModel, pkg: ApiPackage, c
 | contextItem | ApiItem | a context [item](https://rushstack.io/pages/api/api-extractor-model.apiitem/) |
 | style | GenerateStyle | generate style, See the [GenerateStyle](#generatestyle) |
 | resolver | ReferenceResolver | [resolver](#referenceresolver) to resolve markdown content references |
+| customTags | string\[\] |  |
 
 #### Returns
 
@@ -366,7 +447,7 @@ Process of API doc model
 
 **Signature:**
 ```typescript
-export declare function process(model: ApiModel, pkg: ApiPackage, style: GenerateStyle, resolver: ReferenceResolver): string | MarkdownContent[];
+export declare function process(model: ApiModel, pkg: ApiPackage, style: GenerateStyle, resolver: ReferenceResolver, customTags?: string[]): string | MarkdownContent[];
 ```
 
 #### Parameters
@@ -377,6 +458,7 @@ export declare function process(model: ApiModel, pkg: ApiPackage, style: Generat
 | pkg | ApiPackage | a [package](https://rushstack.io/pages/api/api-extractor-model.apipackage/) |
 | style | GenerateStyle | generate style, See the [GenerateStyle](#generatestyle) |
 | resolver | ReferenceResolver | [resolver](#referenceresolver) 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
 
@@ -426,7 +508,7 @@ Process of API doc model
 
 **Signature:**
 ```typescript
-export declare function process(model: ApiModel, pkg: ApiPackage, style: GenerateStyle, resolver: ReferenceResolver): string | MarkdownContent[];
+export declare function process(model: ApiModel, pkg: ApiPackage, style: GenerateStyle, resolver: ReferenceResolver, customTags?: string[]): string | MarkdownContent[];
 ```
 
 #### Parameters
@@ -437,6 +519,7 @@ export declare function process(model: ApiModel, pkg: ApiPackage, style: Generat
 | pkg | ApiPackage | a [package](https://rushstack.io/pages/api/api-extractor-model.apipackage/) |
 | style | GenerateStyle | generate style, See the [GenerateStyle](#generatestyle) |
 | resolver | ReferenceResolver | [resolver](#referenceresolver) 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
 
@@ -520,7 +603,7 @@ Markdown docs processor
 
 **Signature:**
 ```typescript
-export declare type MarkdownProcessor = (model: ApiModel, pkg: ApiPackage, style: GenerateStyle, resolver: ReferenceResolver) => string | MarkdownContent[];
+export declare type MarkdownProcessor = (model: ApiModel, pkg: ApiPackage, style: GenerateStyle, resolver: ReferenceResolver, customTags?: string[]) => string | MarkdownContent[];
 ```
 
 ### ReferenceResolver

package.json

@@ -29,6 +29,7 @@
   "dependencies": {
     "@microsoft/api-extractor-model": "^7.12.0",
     "@microsoft/tsdoc": "^0.12.21",
+    "@microsoft/tsdoc-config": "^0.13.6",
     "chalk": "^4.1.0",
     "debug": "^4.3.1",
     "meow": "^8.0.0"

src/cli.ts

@@ -23,6 +23,10 @@ export const flags = {
     type: 'string',
     alias: 'g',
     default: GenerateStyle.Prefix
+  },
+  'tsdoc-config': {
+    type: 'string',
+    alias: 't'
   }
 } as const
 
@@ -32,17 +36,19 @@ const cli = meow(
     $ api-docs-gen <package1.api.json> <package2.api.json> ...
 
   Options
-    --config, -c              configuration file
+    --config, -c              configration file
     --output, -o              output dierectory that is markdown contents
     --generate-style, -g      document generating style, default 'prefix'
                               'prefix': be able to separated with each package name
                               'directory': be able to separated with each package directory
+    --tsdoc-config, -t        tsdoc configration file
 
   Examples
     $ api-docs-gen package1.api.json
     $ api-docs-gen package1.api.json --output ./docs
     $ api-docs-gen package1.api.json --config docsgen.config.js
     $ api-docs-gen package1.api.json package2.api.json --generate-style directory
+    $ api-docs-gen package1.api.json --tsdoc-config ./tsdoc.json
 `,
   {
     flags
@@ -91,18 +97,26 @@ const genStyle = [GenerateStyle.Prefix, GenerateStyle.Directory].includes(
   : GenerateStyle.Prefix
 debug('packageDocsStyle', genStyleFlag, genStyle)
 
+// tsdoc configratio
+const tsdocConfig = cli.flags['tsdoc-config']
+
 // run
 try {
   ;(async () => {
-    await generate(
-      input,
-      output,
-      genStyle,
+    await generate(input, output, {
+      style: genStyle,
       config,
-      (pkgname: string, filepath: string) => {
+      tsdocConfigPath:
+        tsdocConfig != null
+          ? path.resolve(process.cwd(), tsdocConfig)
+          : undefined,
+      errorOnTSDocConfig: (error: string): void => {
+        console.log(chalk.yellow(`⚠️ Error on TSDoc configration: ${error}`))
+      },
+      done: (pkgname: string, filepath: string): void => {
         console.log(chalk.green(`📦 ${pkgname}: 📝 save ${filepath}`))
       }
-    )
+    })
   })()
 } catch (e) {
   console.error(chalk.red(`[api-docs-gen] ${e.message}`))

src/config.ts

@@ -69,6 +69,7 @@ export interface MarkdownContent {
  * @param pkg - a {@link https://rushstack.io/pages/api/api-extractor-model.apipackage/ | package}
  * @param style - generate style. see the {@link GenerateStyle}
  * @param resolver - the markdown reference {@link ReferenceResolver | resolver}. if you're specfified at {@link Config}, it's passed, else it's not specified passed internal refenrece resolver.
+ * @param customTags - TSDoc custom tags. This parameter is set to an array of custom tag names defined in `--tsdoc-config`.
  *
  * @returns markdown content
  *
@@ -78,7 +79,8 @@ export type MarkdownProcessor = (
   model: ApiModel,
   pkg: ApiPackage,
   style: GenerateStyle,
-  resolver: ReferenceResolver
+  resolver: ReferenceResolver,
+  customTags?: string[]
 ) => string | MarkdownContent[]
 
 /**