kazupon / api-docs-gen

:book: API Documentation generator from `api-extractor` doc model

Hi there 👋 I'm kazupon!

• 🏃 I’m currently working on Intlify projects and projects within the Vue.js and Nuxt ecosystem
• 🌱 I’m currently interested in the future of i18n & WASM
• 🎙 My conference and meetup event slides can be viewed here
• 🏆 Microsoft MVP
• 💬 If you are interested in me, please contact me at issues
• 💖 I need sponsors to keep my projects maintained

My popular OSS projects are as follows: 👇🏼

api-docs-gen's Issues

Fatal error when resolving {@link} expressions.

Example:

/**
 * A
 *
 * @public
 */
export type A = string;

/**
 * {@link A}
 *
 * @public
 */
export type B = number;

Process will exit with code 1, and throw this exception:

TypeError: resolver is not a function
    at getDocSectionContent (/home/jsamr/tmp/api-docs-gen/lib/processor/utils.js:445:46)
    at Object.buildTypeAliasContent (/home/jsamr/tmp/api-docs-gen/lib/processor/utils.js:325:9)
    at buildContents (/home/jsamr/tmp/api-docs-gen/lib/processor/toc.js:78:29)
    at build (/home/jsamr/tmp/api-docs-gen/lib/processor/toc.js:29:9)
    at Object.process [as processor] (/home/jsamr/tmp/api-docs-gen/lib/processor/toc.js:91:12)
    at Object.generate (/home/jsamr/tmp/api-docs-gen/lib/generator.js:30:29)
    at /home/jsamr/tmp/api-docs-gen/lib/cli.js:89:27
    at Object.<anonymous> (/home/jsamr/tmp/api-docs-gen/lib/cli.js:92:7)
    at Module._compile (internal/modules/cjs/loader.js:1251:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1272:10)

To reproduce, apply this patch on master (16585f9):

diff --git a/examples/packages/utilities/src/index.ts b/examples/packages/utilities/src/index.ts
index 64a02e2..6507747 100644
--- a/examples/packages/utilities/src/index.ts
+++ b/examples/packages/utilities/src/index.ts
@@ -70,3 +70,17 @@ export function isSymbol(val: unknown): val is symbol {
 export function isPromise<T = any>(val: unknown): val is Promise<T> { // eslint-disable-line
   return isObject(val) && isFunction(val.then) && isFunction(val.catch)
 }
+
+/**
+ * A
+ *
+ * @public
+ */
+export type A = string;
+
+/**
+ * {@link A}
+ *
+ * @public
+ */
+export type B = number;

I have investigated a little. Resolver is sometimes undefined, so here is a hotfix:

diff --git a/src/processor/utils.ts b/src/processor/utils.ts
index bbc8667..e12d296 100644
--- a/src/processor/utils.ts
+++ b/src/processor/utils.ts
@@ -764,7 +764,7 @@ export function getDocSectionContent(
               codeDestination,
               contextItem
             )
-            if (result.resolvedApiItem) {
+            if (result.resolvedApiItem && resolver) {
               const filepath = resolver(
                 style,
                 result.resolvedApiItem,

Invalid markdown generated from function signatures having parameters typed with parametrized types

Example:

/**
 * A dumb type
 */
export type DumbType<T> = { foo: T };

/**
 *
 * @param dummy - A dummy
 */
export function undumbify<T>(dummy: DumbType<T>): T { return dummy.foo };

Will produce:

### undumbify

...

#### Parameters

| Parameter | Type | Description |
| --- | --- | --- |
| dummy | DumbType<T> | A dummy |

The less-than and greater-than signs should be escaped. Otherwise, it is considered an opening HTML tag.
To reproduce, apply this patch on master (16585f9):

diff --git a/examples/packages/utilities/src/index.ts b/examples/packages/utilities/src/index.ts
index 64a02e2..4ccb387 100644
--- a/examples/packages/utilities/src/index.ts
+++ b/examples/packages/utilities/src/index.ts
@@ -70,3 +70,14 @@ export function isSymbol(val: unknown): val is symbol {
 export function isPromise<T = any>(val: unknown): val is Promise<T> { // eslint-disable-line
   return isObject(val) && isFunction(val.then) && isFunction(val.catch)
 }
+
+/**
+ * A dumb type
+ */
+export type DumbType<T> = { foo: T };
+
+/**
+ *
+ * @param dummy - A dummy
+ */
+export function undumbify<T>(dummy: DumbType<T>): T { return dummy.foo };

And run

yarn example:setup
yarn example:build
yarn example:extract
yarn example:gen
yarn example:docs

template system

• template literal
• vue template

basic generator

• functions
• enumrations
• variables
• type alias
• class
• interface

Vue SFC supporting

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Repository problems

These problems occurred while renovating this repository. View logs.

• WARN: Error updating branch: update failure

Rate-Limited

These updates are currently rate-limited. Click on a checkbox below to force their creation now.

• chore(deps): replace dependency npm-run-all with npm-run-all2 ^5.0.0
• chore(deps): update dependency @types/node to v20
• chore(deps): update dependency eslint to v9
• chore(deps): update pnpm/action-setup action to v3
• fix(deps): update dependency meow to v13
• 🔐 Create all rate-limited PRs at once 🔐

Errored

These updates encountered an error and will be retried. Click on a checkbox below to force a retry now.

• chore(deps): update dependency typescript to v5

Edited/Blocked

These updates have been manually edited so Renovate will no longer make changes. To discard all commits and start over, click on a checkbox.

• fix(deps): update dependency chalk to v5

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): update actions/checkout action to v4
• chore(deps): update actions/setup-node action to v4
• chore(deps): update dependency eslint-config-prettier to v9
• chore(deps): update dependency eslint-plugin-prettier to v5
• chore(deps): update dependency jest-watch-typeahead to v2
• chore(deps): update dependency prettier to v3
• chore(deps): update jest monorepo to v29 (major) (@types/jest, jest, ts-jest)
• chore(deps): update typescript-eslint monorepo to v7 (major) (@typescript-eslint/eslint-plugin, @typescript-eslint/parser)
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

github-actions

.github/workflows/lint.yml

• actions/checkout v3
• pnpm/action-setup v2.4.0
• actions/setup-node v3

.github/workflows/test.yml

• actions/checkout v3
• pnpm/action-setup v2.4.0
• actions/setup-node v3

npm

package.json

• @microsoft/api-extractor-model ^7.12.0
• @microsoft/tsdoc ^0.14.0
• @microsoft/tsdoc-config ^0.16.0
• chalk ^4.1.1
• debug ^4.3.3
• meow ^9.0.0
• @kazupon/lerna-changelog ^4.3.0
• @microsoft/api-extractor ^7.18.21
• @types/debug ^4.1.5
• @types/jest ^27.0.0
• @types/node ^16.11.0
• @typescript-eslint/eslint-plugin ^5.5.0
• @typescript-eslint/parser ^5.5.0
• eslint ^8.4.0
• eslint-config-prettier ^8.3.0
• eslint-plugin-prettier ^4.0.0
• jest ^27.0.0
• jest-watch-typeahead ^1.0.0
• npm-run-all ^4.1.5
• opener ^1.5.2
• prettier ^2.5.0
• shipjs ^0.26.0
• ts-jest ^27.0.0
• typescript ^4.5.2
• vuepress ^1.8.2
• node >= 12
• typescript ^4.5.2
• @microsoft/api-extractor ^7.18.21

---

• Check this box to trigger a request for Renovate to run again on this repository

tsdoc custom tags supporting

docs generating from TypeScript Codes

Implementation

• Use TypeScript Compiler API
• Use Trivia API: https://basarat.gitbook.io/typescript/overview/ast/ast-trivia
  • ref: https://quramy.medium.com/manipulate-comments-with-typescript-api-73d5f1d43d7f

What is your plan for this project?

@kazupon Let's be honest, this project is a very promising alternative to the somehow limited api-documenter! I just want to know if it is worth the time investment. What I mean by that is that I'd love to use it in my open-source projects, and I'd be happy, beyond the reports I have already submitted, to test and send feedbacks on a regular basis. My question is, is it a hobby / prototype or do you have a reasonable confidence that it will receive frequent maintenance and dedication?