このページには、Google Season of Docs で承認されたテクニカル ライティング プロジェクトの詳細が掲載されています。
プロジェクトの概要
- オープンソース組織:
- ScummVM
- テクニカル ライター:
- b-gent
- プロジェクト名:
- Doxygen を使用したソースコード ドキュメントの改善
- プロジェクト期間:
- 標準期間（3 か月）
プロジェクトの説明
現在の ScummVM API（ソースコード）のドキュメントは、https://doxygen.scummvm.org/modules.html で公開されています。
残念ながら、多くの分野で不足しています。
1）実質的に構造はなく、すべての情報が同じレベルに浮かんでいます。
2）C++ 要素のドキュメント化と、ドキュメント化されていない要素の一部がドキュメント化されています。これは、組織が主な問題の 1 つとして挙げているものです。
3）古い非推奨のコンテンツが引き続き出力に表示される。
4）Doxygen のタグ付けの言語と使用方法を一貫させる必要があります。これには、このプロジェクトの今後のドキュメント スタイルガイドの基礎となる一連のルールが必要です。
5）このページで使用されている doxygen CSS を改善して、ScummVM ウェブサイト（https://www.scummvm.org）に似せることができます。
これらの問題はすべて、ドキュメント シーズン プロジェクトで解決できます。
この Season of Docs アプリケーションには、私が提案する改善案を示すために私がプロジェクトで開いた PR ドラフトが添付されています。 https://github.com/scummvm/scummvm/pull/2361 内容の詳細と差分については、説明をご覧ください。
概要は次のとおりです。
1）現在、新しいコントリビューター候補や、現在の API ドキュメントを閲覧するすべてのユーザーにとって最も混乱を招いているのは、構造がないことだと思います。構造化された API ドキュメントを導入することで、読みやすさや見つけやすさが向上し、結果としてドキュメント セットのユーザビリティが向上します。そのため、私の PR では「common」フォルダ内のすべてのヘッダー ファイルに doxygen グループを導入しています。この新しい構造により、OS 関連の API のドキュメントを探す場合、ナビゲーションから簡単に見つけることができます。
2）このドキュメントのビルドを可能にするために、新しい doxygen 構成ファイルが設定されています。
3）ドキュメントセット全体で使用されるすべてのリンクを単一ソースから取得できる「links.doxyfile」ファイル。doxygen を使用する場合に便利なメカニズムです。
4）変更された doxygen CSS。これは現在、別のオープンソース プロジェクトから取得されており、出発点にすぎません。理想的には、doxygen ページの外観は ScummVM ウェブページとほぼ一致している必要があります。
PR ではカバーされないものの、必ず対応する必要があるのはコンテンツ自体です。つまり、ドキュメント化されていないコードの重要な部分、十分にドキュメント化されていない部分、ドキュメントから削除する必要がある古いコードの部分を特定します。これまでこのプロジェクトに携わったことがないため、これを達成するにはメンターの指導が必要です。
もちろん、PR の内容を何か実装するかどうかは、組織との話し合い次第です。行動は言葉よりも雄弁であるという考えから、アプリケーションで説明するだけでなく、できることを示すことにしました。
この組織は、このプロジェクトの概要として次のタイムラインを提供しています。 週間 主なタスク 週 0（9 月 14 日より前） 提案の議論とレビュー 週 1（9 月 14 日） Doxygen ビルドのセットアップ 週 2（9 月 21 日） Doxygen スキンの更新（優先度低） 週 3（9 月 28 日） 共通コード - OSystem、FS、データ構造、文字列など 週 4（10 月 5 日） 共通コード - 続編 週 5（10 月 12 日） エンジン - 共通コードとサンプル エンジン 週 6（10 月 19 日） グラフィック 週 7（10 月 26 日） 音声 週 8（11 月 2 日） 動画、画像 週 9（11 月 9 日） バックエンド - プラットフォーム、グラフィック、イベント 週 10（11 月 23 日） バックエンド - 続編 週 11（11 月 30 日） プロジェクトの概要と送信
提案したい変更は、すでに述べたように、最初に構造に取り組むことです。これは、doxygen ビルドのセットアップ（すでに大部分が完了している）と Doxygen スキンの更新とともに、1 週目と 2 週目に行うことができます。その後は、メンターと一緒にさまざまな領域を 1 つずつ確認し、問題を特定して doxygen ドキュメントを改善するのが最も理にかなっていると思います。
これは標準的な長さのプロジェクトですが、GSoD プロジェクト終了後にできる、API ドキュメントに関連する改善が他にもあるはずです。たとえば、ドキュメント スタイルガイドを作成してウィキに追加し、コントリビューターが追加するコードをどのようにドキュメント化すべきかを認識できるようにします。
GSoD が終了しましたら、このようなタスクについてはお手伝いいたします。ScummVM には、API ドキュメントの品質とユーザビリティを確保する技術ライターが必要だと思います。プラグインの使用方法に関するガイドの作成など、今後のドキュメント プロジェクトについてもサポートさせていただきます。