リファレンス執筆ガイド
公開されるリファレンスは、ヘッダの /// コメントだけから生成する。Markdown を
手書きする場所はない。ページの体裁を変えたいときは tools/reference/ を、
文章を直したいときはヘッダを編集する。
mise run docs # docs/generated/ にページを生成する
mise run docs-check # 生成したうえで網羅率・例・リンクを検査する
mise run docs-site # 検証結果なしでサイトのソースを _jekyll/ に組み立てる
生成先の docs/generated/ は Git 管理外である。CI が検査時とサイト構築時に生成する。
ページの構成
生成されるページは cpprefjp と同じ 2 段構成にしている。
| ページ | 生成元 | 内容 |
|---|---|---|
reference/<category>/<header> |
ヘッダ全体 | 概要、インクルード、提供する型・関数の一覧、例、検証、依存関係、実装 |
reference/<category>/<header>/<name> |
型 1 つ・関数 1 つ | シグネチャ、概要、パラメータ、戻り値、計算量、メンバ一覧と詳細、関連項目 |
同名のオーバーロードは 1 ページにまとまる。記述が同じなら 1 つの説明に、違えば
(1) (2) と番号が振られる。クラスのメンバは「構築・破棄 / メンバ関数 / 演算子 /
静的メンバ関数 / メンバ型 / メンバ変数」に自動で分類され、一覧表に収まらない情報
（パラメータ・戻り値・事前条件・備考・複数の記述）を持つものだけが詳細節を持つ。
private のメンバ、記述のないエンティティはページに出ない。
public な基底（CRTP の基底を含む）の public メンバは、派生型のページにも
「基底 X から継承」と添えて載る。派生側に同名のメンバがあれば基底側は載らない
（C++ の名前隠蔽と同じ）。コンストラクタ・デストラクタは引き継がない。
そのため共通部分を基底へ括り出すときは、記述は基底のメンバに 1 回だけ書けばよい。
派生型ごとにラッパーや using Base::f; を書き直す必要はない。基底は記述付きの
クラスとしてどこかのヘッダで宣言されていること（lib/internal/ でよい）。
タグ
| タグ | 用途 |
|---|---|
@file |
そのブロックをヘッダ自身の説明にする。ページ見出しと概要になる |
@brief |
1 行の説明。一覧表のセルに入るので簡潔に書く |
@details |
段落。複数書けば複数段落になる |
@tparam / @param |
テンプレート引数・引数の説明 |
@return |
戻り値 |
@pre |
呼び出し側が保証すべき事前条件 |
@complexity |
時間計算量。重要なら空間計算量も |
@note / @warning |
備考・注意 |
@see |
参考。URL はリンクになる |
@code … @endcode |
例。そのままコンパイルして実行できる完全なプログラムを書く |
@file ブロックは include 群の直後に置き、次の要素の説明とは空行で区切る。
主要な型が 1 つに定まるヘッダでは省略してよく、その型の @brief がページ見出しになる。
#pragma once
#include <vector>
/// @file
/// @brief 素集合データ構造 (Union-Find)
/// @details 要素の集合を併合し、2 要素が同じ連結成分に属するかを管理する。
/// @note 代表元は併合順に依存するため、特定の添字になるとは限らない。
/// @code
/// #include <iostream>
/// #include "data_structure/union_find.hpp"
///
/// int main() {
/// union_find uf(5);
/// uf.unite(0, 1);
/// std::cout << uf.same(0, 1) << '\n';
/// }
/// @endcode
/// @brief 素集合データ構造
/// @complexity 構築は $O(n)$、併合は償却 $O(\alpha(n))$
struct union_find {
@code の中身は g++ -std=c++23 -I lib でコンパイルして実際に実行され、標準出力が
ページの「出力」節になる。壊れた例は mise run docs-check が落とす。入力は空なので、
標準入力を読む例は書かない。
記述方針
- 数式は
$...$で囲む（MathJax が組版する）。計算量・添字・冪・総和・不等号は すべて数式にし、O(n log n)や\sum_{i=1}^{n}を地の文に置かない。 識別子（型名・引数名・メンバ名）はバッククォートで、数学的な量は数式で書き分ける。 数式の中では\log・\sqrt・\alphaを使い、degのような綴りは\mathrm{...}にするか「degを $d$ として」と言い換える。Doxygen の@cは生成器が解釈しないので 使わない（バッククォートを使う）。 数式は LaTeX のまま書いてよい（|x|・\_・h'などは生成器が退避して MathJax に そのまま渡す）。 - 区間は半開区間 $[l, r)$ と明記する。
- 失敗を表す戻り値、
assertされる事前条件、空入力の挙動を書く。 - 時間計算量を書く。重要な場合は空間計算量も書く。
- テンプレート引数に要求される concept や演算を書く。
- コードから読み取れない保証を推測で追加しない。
- 内部実装より、利用者から観測できる挙動を優先する。
検査
mise run docs-check は次を確かめる。
- 公開ヘッダに概要（
@fileの@briefか、主要な型の@brief）があること ///コメントの数式が$...$で囲われていること- 公開エンティティに
@briefがあること - 関数・演算子・コンストラクタに
@complexityがあること @codeの例がコンパイルでき、実行が成功すること- 生成ページ同士のリンクが切れていないこと
- ページ数・計算量の記述数が
docs/reference.tomlの下限を下回らないこと
下限値は現状維持のためのもので、公開 API を増やしたら同じ PR で引き上げる。
lib/internal/ と lib/template/ は網羅率の対象外だが、ページは生成される。