インストール

モジュールをインストールします 

  1. npm install @wordpress/docgen --save-dev

注意: このパッケージは、長期サポートステータスのあるNode.jsバージョンを必要とします（アクティブLTSまたはメンテナンスLTSリリースを確認）。古いバージョンとは互換性がありません。

使用法

  1. npx docgen <entry-point.js>

このコマンドは、すべてのエクスポートとそのJSDocコメントを含むentry-point-api.mdという名前のファイルを生成します。

CLIオプション

  • –formatter (String): 出力ファイルの内容を制御するカスタムフォーマッタへのパス。これは、次の入力を受け取る関数をエクスポートするCommonJSモジュールである必要があります:
    • rootDir (String): docgenから見た現在の作業ディレクトリ。
    • docPath (String): 生成する出力ドキュメントのパス。
    • symbols (Array): 見つかったシンボル。
  • –ignore (RegExp): 名前が一致するシンボルを無視するために使用される正規表現。
  • –output (String): APIドキュメントを含む出力ファイル。
  • –to-section (String): 生成されたドキュメントをMarkdown出力のこのセクションに追加します。デフォルトのMarkdownフォーマッタによって使用されます。--outputに依存し、カスタム--formatterは無視されます（あれば）。
  • –to-token: 生成されたドキュメントをMarkdown出力の開始トークンと終了トークンの間に埋め込みます。デフォルトのMarkdownフォーマッタによって使用されます。--outputに依存し、カスタム--formatterは無視されます（あれば）。
    • 開始トークン: <!-- START TOKEN(Autogenerated API docs) -->
    • 終了トークン: <!-- END TOKEN(Autogenerated API docs) -->
  • –use-token (String): このオプションを使用すると、トークン間の文字列をカスタマイズできます。たとえば、--use-token my-apiは開始トークン<!-- START TOKEN(my-api) -->と終了トークン<!-- END TOKEN(my-api) -->を探します。--to-tokenに依存します。
  • –debug: デバッグモードで実行し、デバッグに役立つ中間ファイルを出力します。

Babel設定

  2. それがない場合、`````@wordpress/docgen`````はデフォルトオプションで実行されます。言い換えれば、JSXや他の高度な構文を解析できません。  
  3.  <a name="examples"></a>
  6. ## 例
  8. <a name="default-export"></a>
  11. ### デフォルトエクスポート
  13. エントリーポイント `````index.js`````:  
  16. ``````bash
  17. /**
  18.  * Adds two numbers.
  19.  *
  20.  * @param {number} term1 First number.
  21.  * @param {number} term2 Second number.
  22.  * @return {number} The result of adding the two numbers.
  23.  */
  24. export default function addition( term1, term2 ) {
  25.    // Implementation would go here.
  26. }
  27. `

npx docgen index.jsの出力はindex-api.jsになります: 

  3. # API
  5. ## デフォルト
  7. [example.js#L8-L10](example.js#L8-L10)
  9. 2つの数を加算します。
  11. **パラメータ**
  13. -   **term1** `number`: 最初の数。
  14. -   **term2** `number`: 2番目の数。
  16. **戻り値**

名前付きエクスポート

エントリーポイント index.js: 

  1. /**
  2.  * Adds two numbers.
  3.  *
  4.  * @param {number} term1 First number.
  5.  * @param {number} term2 Second number.
  6.  * @return {number} The result of adding the two numbers.
  7.  */
  8. function addition( term1, term2 ) {
  9.    return term1 + term2;
  10. }
  12. /**
  13.  * Adds two numbers.
  14.  *
  15.  * @deprecated Use `addition` instead.
  16.  *
  17.  * @param {number} term1 First number.
  18.  * @param {number} term2 Second number.
  19.  * @return {number} The result of adding the two numbers.
  20.  */
  21. function count( term1, term2 ) {
  22.    return term1 + term2;
  23. }
  25. export { count, addition };

npx docgen index.jsの出力はindex-api.jsになります: 

  3. # API
  5. ## 加算
  7. [example.js#L25-L25](example.js#L25-L25)
  9. 2つの数を加算します。
  11. **パラメータ**
  13. -   **term1** `number`: 最初の数。
  14. -   **term2** `number`: 2番目の数。
  16. **戻り値**
  19. ## カウント
  21. [example.js#L25-L25](example.js#L25-L25)
  23. > **非推奨** `addition`を使用してください。
  25. 2つの数を加算します。
  27. **パラメータ**
  29. -   **term1** `number`: 最初の数。
  30. -   **term2** `number`: 2番目の数。
  32. **戻り値**

名前空間エクスポート

エントリーポイントをindex.jsとします: 

  1. export * from './count';
  3. ``````bash
  4. /**
  5.  * Substracts two numbers.
  6.  *
  7.  * @example
  8.  *
  9.  * ```js
  10.  * const result = substraction( 5, 2 );
  11.  * console.log( result ); // Will log 3
  12.  * ```
  13.  *
  14.  * @param {number} term1 First number.
  15.  * @param {number} term2 Second number.
  16.  * @return {number} The result of subtracting the two numbers.
  17.  */
  18. export function substraction( term1, term2 ) {
  19.    return term1 - term2;
  20. }
  22. /**
  23.  * Adds two numbers.
  24.  *
  25.  * @example
  26.  *
  27.  * ```js
  28.  * const result = addition( 5, 2 );
  29.  * console.log( result ); // Will log 7
  30.  * ```
  31.  *
  32.  * @param {number} term1 First number.
  33.  * @param {number} term2 Second number.
  34.  * @return {number} The result of adding the two numbers.
  35.  */
  36. export function addition( term1, term2 ) {
  37.    // Implementation would go here.
  38.    return term1 - term2;
  39. }
  40. `

npx docgen index.jsの出力はindex-api.jsになります: 

  3. # API
  5. ## 加算
  7. [example-module.js#L1-L1](example-module.js#L1-L1)
  9. 2つの数を加算します。
  11. **使用法**
  13. const result = addition( 5, 2 );
  14. console.log( result ); // 7をログに出力します
  16. **パラメータ**
  18. -   **term1** `number`: 最初の数。
  19. -   **term2** `number`: 2番目の数。
  21. **戻り値**
  24. ## 減算
  26. [example-module.js#L1-L1](example-module.js#L1-L1)
  28. 2つの数を減算します。
  30. **使用法**
  32. const result = substraction( 5, 2 );
  33. console.log( result ); // 3をログに出力します
  35. **パラメータ**
  37. -   **term1** `number`: 最初の数。
  38. -   **term2** `number`: 2番目の数。
  40. **戻り値**

TypeScriptサポート

エントリーポイント index.ts: 

  1. /**
  2.  * Adds two numbers.
  3.  *
  4.  * @param term1 First number.
  5.  * @param term2 Second number.
  6.  * @return The result of adding the two numbers.
  7.  */
  8. export default function addition( term1: number, term2: number ): number {
  9.    // Implementation would go here.
  10. }

npx docgen index.tsの出力はindex-api.jsになります: 

  3. # API
  5. ## デフォルト
  7. [example.js#L8-L10](example.js#L8-L10)
  9. 2つの数を加算します。
  11. **パラメータ**
  13. -   **term1** `number`: 最初の数。
  14. -   **term2** `number`: 2番目の数。
  16. **戻り値**

このパッケージへの貢献

これはGutenbergプロジェクトの一部である個別のパッケージです。このプロジェクトはモノレポとして整理されています。特定の目的を持つ複数の自己完結型ソフトウェアパッケージで構成されています。このモノレポ内のパッケージはnpmに公開され、WordPressや他のソフトウェアプロジェクトで使用されています。

このパッケージやGutenberg全体への貢献について詳しく知りたい場合は、プロジェクトの主要な貢献者ガイドをお読みください。