-
Notifications
You must be signed in to change notification settings - Fork 4.2k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
New package to auto-generate public API documentation (#13329)
- Loading branch information
Showing
112 changed files
with
8,511 additions
and
34 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1 @@ | ||
package-lock=false |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
## 1.0.0 (Unreleased) | ||
|
||
- Initial release |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,250 @@ | ||
# `docgen` | ||
|
||
`docgen` helps you to generate the _public API_ of your code. Given an entry point file, it outputs the ES6 export statements and their corresponding JSDoc comments in human-readable format. | ||
|
||
Some characteristics: | ||
|
||
* If the export statement doesn't contain any JSDoc, it'll look up for JSDoc up to the declaration. | ||
* It can resolve relative dependencies, either files or directories. For example, `import default from './dependency'` will find `dependency.js` or `dependency/index.js` | ||
|
||
## Installation | ||
|
||
Install the module | ||
|
||
```bash | ||
npm install @wordpress/docgen --save-dev | ||
``` | ||
|
||
## Usage | ||
|
||
```bash | ||
npx docgen <entry-point.js> | ||
``` | ||
|
||
This command will generate a file named `entry-point-api.md` containing all the exports and their JSDoc comments. | ||
|
||
### CLI options | ||
|
||
* **--formatter** `(String)`: A path to a custom formatter to control the contents of the output file. It should be a CommonJS module that exports a function that takes as input: | ||
* *rootDir* `(String)`: current working directory as seen by docgen. | ||
* *docPath* `(String)`: path of the output document to generate. | ||
* *symbols* `(Array)`: the symbols found. | ||
* **--ignore** `(RegExp)`: A regular expression used to ignore symbols whose name match it. | ||
* **--output** `(String)`: Output file that will contain the API documentation. | ||
* **--to-section** `(String)`: Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter. Depends on `--output` and bypasses the custom `--formatter` passed, if any. | ||
* **--to-token**: Embed generated documentation within the start and end tokens in the Markdown output. To be used by the default Markdown formatter.Depends on `--output` and bypasses the custom `--formatter` passed, if any. | ||
* Start token: `<!-- START TOKEN(Autogenerated API docs) -->` | ||
* End token: `<!-- END TOKEN(Autogenerated API docs) -->` | ||
* **--use-token** `(String)`: This options allows you to customize the string between the tokens. For example, `--use-token my-api` will look up for the start token `<!-- START TOKEN(my-api) -->` and the end token `<!-- END TOKEN(my-api) -->`. Depends on `--to-token`. | ||
* **--debug**: Run in debug mode, which outputs some intermediate files useful for debugging. | ||
|
||
## Examples | ||
|
||
### Default export | ||
|
||
Entry point `index.js`: | ||
|
||
```js | ||
/** | ||
* Adds two numbers. | ||
* | ||
* @param {number} term1 First number. | ||
* @param {number} term2 Second number. | ||
* @return {number} The result of adding the two numbers. | ||
*/ | ||
export default function addition( term1, term2 ) { | ||
// Implementation would go here. | ||
} | ||
``` | ||
|
||
Output of `npx docgen index.js` would be `index-api.js`: | ||
|
||
```markdown | ||
# API | ||
|
||
## default | ||
|
||
[example.js#L8-L10](example.js#L8-L10) | ||
|
||
Adds two numbers. | ||
|
||
**Parameters** | ||
|
||
- **term1** `number`: First number. | ||
- **term2** `number`: Second number. | ||
|
||
**Returns** | ||
|
||
`number` The result of adding the two numbers. | ||
``` | ||
|
||
### Named export | ||
|
||
Entry point `index.js`: | ||
|
||
```js | ||
/** | ||
* Adds two numbers. | ||
* | ||
* @param {number} term1 First number. | ||
* @param {number} term2 Second number. | ||
* @return {number} The result of adding the two numbers. | ||
*/ | ||
function addition( term1, term2 ) { | ||
return term1 + term2; | ||
} | ||
|
||
/** | ||
* Adds two numbers. | ||
* | ||
* @deprecated Use `addition` instead. | ||
* | ||
* @param {number} term1 First number. | ||
* @param {number} term2 Second number. | ||
* @return {number} The result of adding the two numbers. | ||
*/ | ||
function count( term1, term2 ) { | ||
return term1 + term2; | ||
} | ||
|
||
export { count, addition }; | ||
``` | ||
|
||
Output of `npx docgen index.js` would be `index-api.js`: | ||
|
||
```markdown | ||
# API | ||
|
||
## addition | ||
|
||
[example.js#L25-L25](example.js#L25-L25) | ||
|
||
Adds two numbers. | ||
|
||
**Parameters** | ||
|
||
- **term1** `number`: First number. | ||
- **term2** `number`: Second number. | ||
|
||
**Returns** | ||
|
||
`number` The result of adding the two numbers. | ||
|
||
## count | ||
|
||
[example.js#L25-L25](example.js#L25-L25) | ||
|
||
> **Deprecated** Use `addition` instead. | ||
|
||
Adds two numbers. | ||
|
||
**Parameters** | ||
|
||
- **term1** `number`: First number. | ||
- **term2** `number`: Second number. | ||
|
||
**Returns** | ||
|
||
`number` The result of adding the two numbers. | ||
``` | ||
|
||
### Namespace export | ||
|
||
Let the entry point be `index.js`: | ||
|
||
```js | ||
export * from './count'; | ||
``` | ||
|
||
with `./count/index.js` contents being: | ||
|
||
```js | ||
/** | ||
* Substracts two numbers. | ||
* | ||
* @example | ||
* | ||
* ```js | ||
* const result = substraction( 5, 2 ); | ||
* console.log( result ); // Will log 3 | ||
* ``` | ||
* | ||
* @param {number} term1 First number. | ||
* @param {number} term2 Second number. | ||
* @return {number} The result of subtracting the two numbers. | ||
*/ | ||
export function substraction( term1, term2 ) { | ||
return term1 - term2; | ||
} | ||
|
||
/** | ||
* Adds two numbers. | ||
* | ||
* @example | ||
* | ||
* ```js | ||
* const result = addition( 5, 2 ); | ||
* console.log( result ); // Will log 7 | ||
* ``` | ||
* | ||
* @param {number} term1 First number. | ||
* @param {number} term2 Second number. | ||
* @return {number} The result of adding the two numbers. | ||
*/ | ||
export function addition( term1, term2 ) { | ||
// Implementation would go here. | ||
return term1 - term2; | ||
} | ||
``` | ||
|
||
Output of `npx docgen index.js` would be `index-api.js`: | ||
|
||
````markdown | ||
# API | ||
|
||
## addition | ||
|
||
[example-module.js#L1-L1](example-module.js#L1-L1) | ||
|
||
Adds two numbers. | ||
|
||
**Usage** | ||
|
||
```js | ||
const result = addition( 5, 2 ); | ||
console.log( result ); // Will log 7 | ||
``` | ||
|
||
**Parameters** | ||
|
||
- **term1** `number`: First number. | ||
- **term2** `number`: Second number. | ||
|
||
**Returns** | ||
|
||
`number` The result of adding the two numbers. | ||
|
||
## substraction | ||
|
||
[example-module.js#L1-L1](example-module.js#L1-L1) | ||
|
||
Substracts two numbers. | ||
|
||
**Usage** | ||
|
||
```js | ||
const result = substraction( 5, 2 ); | ||
console.log( result ); // Will log 3 | ||
``` | ||
|
||
**Parameters** | ||
|
||
- **term1** `number`: First number. | ||
- **term2** `number`: Second number. | ||
|
||
**Returns** | ||
|
||
`number` The result of subtracting the two numbers. | ||
```` | ||
|
||
<br/><br/><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,44 @@ | ||
#!/usr/bin/env node | ||
|
||
const docgen = require( '../src' ); | ||
|
||
const optionator = require( 'optionator' )( { | ||
prepend: 'Usage: node <path-to-docgen> <relative-path-to-entry-point>', | ||
options: [ { | ||
option: 'formatter', | ||
type: 'String', | ||
description: 'A custom function to format the generated documentation. By default, a Markdown formatter will be used.', | ||
}, { | ||
option: 'output', | ||
type: 'String', | ||
description: 'Output file to contain the API documentation.', | ||
}, { | ||
option: 'ignore', | ||
type: 'RegExp', | ||
description: 'A regular expression used to ignore symbols whose name match it.', | ||
}, { | ||
option: 'to-section', | ||
type: 'String', | ||
description: 'Append generated documentation to this section in the Markdown output. To be used by the default Markdown formatter.', | ||
dependsOn: 'output', | ||
}, { | ||
option: 'to-token', | ||
type: 'Boolean', | ||
description: 'Embed generated documentation within this token in the Markdown output. To be used by the default Markdown formatter.', | ||
dependsOn: 'output', | ||
}, { | ||
option: 'use-token', | ||
type: 'String', | ||
default: 'Autogenerated API docs', | ||
description: 'Add this string to the start/end tokens.', | ||
dependsOn: 'to-token', | ||
}, { | ||
option: 'debug', | ||
type: 'Boolean', | ||
default: false, | ||
description: 'Run in debug mode, which outputs some intermediate files useful for debugging.', | ||
} ], | ||
} ); | ||
|
||
const options = optionator.parseArgv( process.argv ); | ||
docgen( options._[ 0 ], options ); |
Oops, something went wrong.