@rdlabo/capacitor-docgen

@rdlabo/capacitor-docgen is an independently maintained enhancement fork of Ionic's @capacitor/docgen. It keeps the upstream CLI, Markdown placeholders, output helpers, and exported functions, while extending the parser result and generated content with interface inheritance.

The comparison in these docs is pinned to @rdlabo/capacitor-docgen@0.4.1 and upstream @capacitor/docgen@0.3.1, the current npm releases. It does not imply that the fork is an official Ionic package.

Install

npm install --save-dev @rdlabo/capacitor-docgen

Use the same docgen command and flags as upstream:

npx docgen --api MyPlugin --output-readme README.md --output-json dist/docs.json

The input README must already contain the placeholders that docgen updates:

<docgen-index></docgen-index>

<docgen-api></docgen-api>

Do not install both packages as direct dependencies in one project: both publish the docgen binary. Choose the fork when inherited interface members must appear in generated documentation.

Inheritance enhancement

Upstream records only the members written directly in an interface. The fork also reads a TypeScript extends clause and appends methods and properties from the resolved base interface.

export interface SharedOptions {
  requestId?: string;
}

export interface CreateOptions extends SharedOptions {
  value: string;
}

export interface MyPlugin {
  create(options: CreateOptions): Promise<void>;
}

With the fork, the generated CreateOptions table contains both value and requestId. The fork can also resolve a base named through a type alias when that alias points to an interface.

The released fork README says to add an @extends JSDoc tag. That instruction is stale for v0.4.1: the implementation reads the TypeScript heritage clause directly and does not use the tag to resolve inheritance. Write valid TypeScript extends; an @extends tag is not required.

See Differences from upstream for the exact changed surfaces and current limitations.

Pinned sources

• Fork parser v0.4.1
• Fork public types v0.4.1
• Upstream parser v0.3.1
• Upstream public types v0.3.1

Documentation

• Differences from Upstream

Full documentation: https://docs.rdlabo.dev/projects/capacitor-docgen

CLI

The easiest way to run docgen is to install @rdlabo/capacitor-docgen as a dev dependency and add the command to the package.json scripts. In the example below, HapticsPlugin is the primary interface:

docgen --api HapticsPlugin --output-readme README.md

Flag	Alias	Description
--api	-a	The name of the primary application programming interface. Required
--output-readme	-r	Path to the markdown file to update. Note that the file must already exist. Required
--output-json	-j	Path to write the raw docs data as a json file.
--project	-p	Path to the project's tsconfig.json file, same as the project flag for TypeScript's CLI. By default it'll attempt to find this file.

package.json script

{
  "scripts": {
    "docgen": "docgen --api HapticsPlugin --output-readme README.md"
  }
}

API

The same API that's available to the CLI can also be imported from @rdlabo/capacitor-docgen.

Related

• Capacitor
• Capacitor Community Plugins