この取り組みは、インラインドキュメントの取り組みに続いて、特に JavaScript に重点を置いています。目標は、WordPress のすべての JavaScript ファイルをきちんとドキュメント化し、このドキュメントに簡単にアクセスできるようにすることです。WordPress コアにおける JavaScript の開発は急速にスピードアップしており、現在のコアエディターと REST API に焦点を当てるとますます顕著になってきています。これらの開発をできるだけスムーズに進めるために、既存のコードをしっかりとドキュメント化する必要があります。
インラインドキュメントとは何かをよく知らない人は、私たちのページであるインラインドキュメントの規格についてを読んでみてください。
どの JS ファイルをドキュメント化するべきですか ?
ドキュメント用の JS ファイルを追跡している3つのページがあります。
- 未対応の JS ドキュメントファイル: これらのファイルをドキュメント化する作業はまだ誰も行っていません。投稿にコメントすることで、ファイルを担当できます。
- 進行中の JS ドキュメントファイルのチケット: これらのファイルには、ドキュメントを含むパッチがあるか、誰かがドキュメントのパッチを作成する作業しています。
- クローズされた JS ドキュメントファイルのチケット: これらのファイルは、すでにドキュメント化されています。
参加方法について
インラインドキュメントは「技術的」なドキュメントとみなされるため、WordPress のコードベースについてある程度の知識が必要となり、コードを理解する必要があります。
1. JavaScript ドキュメント規約をはじめ、書式ガイドラインやドキュメント作成のヒントをよく理解してください。
2. Varying Vagrant Vagrants (VVV) を使って、WordPress コードベース開発版のローカルコピーをセットアップします。WordPress は バージョン管理に SVN を使用していますが、Git を使うこともできます (その方法は VVV のリンク先にあります)。
3. Trac チケットの作り方はチケットを開くを読んでください。
4. パッチの作成:
- ドキュメント化を開始するファイルを担当する。
- ファイルを編集したりパッチを作成したりする前に、必ず WordPress trunk のローカルコピーを更新してください。必要に応じて
svn up
やgit pull
を使ってください。 - WordPress の SVN または Git チェックアウトのルートディレクトリからパッチを生成してください。
- パッチファイルの名前は 12345.patch や 12345.diff のように、作成した Trac チケット番号と同じ名前にするのがよいでしょう。拡張子はどちらでもかまいません。
5. パッチの提出方法:
- Core Trac で、ファイルに対する新しいチケットを作成します。
- 提案される Title の形式は、”JSDoc correction for path/to/file.js” または “Improve documentation for path/to/file.js” のようになります。
- 「タイプ」は、defect (bug) でなければなりません。
- ファイルが関連付けられている「コンポーネント」にチケットを割り当てます。
- 「バージョン」は空欄にしてください。
- docs と JavaScript をクリックして「フォーカス」を追加します。
- これは、
Media
コンポーネントにdocs
とjavascript
をフォーカスし、JSDocs correction for
というタイトルをつけて新しいチケットを作成するショートカットリンクです。あとは、タイトルにファイル名を追加するだけです。新しい JS ドキュメントチケット
- 作成した Trac チケットにパッチをアップロードし、キーワード has-patch を追加してください。
- アップロードしたパッチについて、必ずコメントを残してください。パッチをアップロードしただけでは、このチケットを見ている人には通知されません。
- 備考: ドキュメントの変更は、チケットが特に両方を要求していない限り、(たとえホワイトスペースであっても) コードの変更と一緒にしてはいけません。
6. また、必要に応じて引き続きインラインドキュメントに関連した Trac チケット にも貢献できます。
- チケットに needs-patch や needs-refresh と書かれている場合、既存のパッチに手を加えたり、最新のトランクに対して更新する必要があるかもしれません。どんな小さなことでも役に立つのです !
問い合わせ先
質問は、Slack の #docs チャンネルで受け付けています。JavaScript に関する質問の場合は、#core-js チャンネルに参加できます。