cpprefjp完成のお知らせと、これからの相談

[faithandbrave]

C++29までの作業が一通り完了し、C互換ライブラリ・iostream・locale周りも必要なものは一通りおわりました。
これで、cpprefjpが当初から目指していた範囲としては、一旦完成となります。

まずはここまでご尽力いただいた方々、ありがとうございます。
cpprefjpはC++での開発をするにあたって必要不可欠なインフラへと成長してこれたのは、みなさんがさまざまな視点で貢献くださったからだと思います。

cpprefjpの今後に向けてご相談

さて、今後に向けてですが、AIの力も借りることで執筆スピードが向上し、検証もしやすくなったので、cpprefjpが扱う範囲をさらに拡大していけると考えています。
とくにcpprefjpは言語側が弱いというのはさまざまなところで言われているので、そのあたりをカバーしていければと思っています。

またほかにもやりたいことはいろいろでてくるかと思いますので、やりたいことがあれば実現させるかはわからないですが、書いていってほしいです。
また、優先的に対応する順序も決めていきたいです。

まず私が考える優先順位を書きます。

1. 言語の入門

• C++入門もcpprefjpで完結させられるといいなと思っています
• どこまで平易に書くか、どこまで詳細に書くかとかあると思いますが、平易な説明 + 詳細を知りたい人向けの説明で2種類書くといいのかなと思っています
• intro階層とするとadvancedなことが書きにくいので、tutorial階層とかどうかなと思ってます
• Goみたいなインタラクティブな入門サイトである必要はないと思っています
• 平易な説明としては、Elixirの入門サイトは見晴らしがよく、さっと学べるのでいいかなと思ってます https://elixir-lang.jp/getting-started/case-cond-and-if.html
• コンパイラのインストール・使い方もスクリーンショット付きで書けるといいなと思ってます
• コンテナの選択や並行処理の基本みたいな、ライブラリ部分もある程度カバーできるといいかなと思います。イテレータとはなにか、みたいなのも。
• まずはたたき台のページを書いて、説明の粒度とか書き方をレビューし、雛形ページを作ってから量産する想定です
• 言語バージョンによって最適な書き方が変わるので、言語バージョンごとにページを用意するのがいいかなと思っています。多重管理にはなってしまいますが、そこはAIで一部バージョンのみの更新になっていないかを都度チェックできるかなと思います。一度作ったらそんなに変えないですしね
• ツールの新機能はあまり必要はない気はしていますが、言語バージョンを切り替えるドロップダウンリストみたいなのはあるといい気がしています

2. 言語機能のリファレンス

• どこまで詳細に書くかはありますが、いまバージョンごとの差分を書いているものを、ある機能がどのバージョンでどのように変わったのかを確認しながら機能を1ページで見れるといいかなと思っています
• cpprefjpらしく、この仕様はなんのためのものでどういう状況で必要なのかに答えるための例と補足は充実させたいです
• lang/reference階層を作る想定です

3. ライブラリリファレンスの使いやすさ向上

• 「パラメータ」欄は、一部ページにはありますが、改めて追加してもいい気がしています。これから追加するのは大変ですが、各パラメータがどういう意味・役割なのかはわかるといいかなと思っています
• さらなる例の追加。特徴的な仕様を説明する例はもっとあっていいかなと思っています
  • たとえばshared_ptrのaliasing constructorとかは、説明はありますがさらっとしているので、独自した例とともに説明できるといいかなと
  • ほかにも、1ページに1例で済ませている多くのページに、基本的な使い方以外にも、ユースケースの例や、よくある間違いの例 (accumulateへの初期値0LLみたいな) とかも載せられるといいかなと思っています
• ライブラリ一般の要件、コンテナの要件、アロケータ要件なども現状書く場所がないので、余裕があれば書いていきたいです (現状なくてもあまり困ってなさそうな気はしますが)

4. C言語対応

• C言語の解説は最新に追従できているサイトはなかなかないので、cpprefjpの対応が求められる領域な気はしています
• C++とは足並みが合ってない進化もいろいろ進んでいるようですので (10進浮動小数点数とか)、私たちもついていけなくなる前に、C言語のバージョンアップも管理していけるといいのかなと思ってます

[faithandbrave]

• https://x.com/ChShersh/status/2096570999206486260

cppreferenceで嫌いな点は、重要な情報が雑音と区別がつかないことです。
std::shared_ptrのコンストラクタ#8は他のどれかと大差ないように見えますが、aliasing constructorと呼ばれる非常に重要なもので、衝撃的です。

cpprefjpに対してではないですが、たしかに、と思ったポストです。
リファレンスなのでなかなか「これが重要な仕様！」とは書きにくいですが、重要な仕様のためのサンプルコードやコード片は追加であってもいいのかなと思います。

[faithandbrave]

追加のサンプルコードで書きやすいのは、C++xxからこういうコードが書けるようになった、ですかね。
それと、従来のこういう書き方は (cpprefjpとして) 推奨しない、とか。

• https://x.com/oki_mik/status/2094355475517300791

std::equalの3引数版は長さチェックされなくてクラッシュする場合があるので、推奨しない、とか (なぜかdeprecatedにならないけど、4引数版を推奨したい)。

[yohhoy]

C++26（＆現時点のC++29WD）までの追従、おつかれさまでした 🎉

個人的にはcpprefjpに求める優先度・重要度を下記順で考えています。

• ライブラリリファレンスの使いやすさ向上
  • 単純なライブラリ仕様からは想像しづらい利用方法、単一クラス／関数ではなく組み合わせて使う複合的な機能群などの説明文や例示コードを増補していけるとベスト。
• 言語機能のリファレンス
  • 「C++に関するリファレンスサイト」という立ち位置的には、言語機能についても手を広げるのはあり。
• C言語対応
  • C独自／C++未導入の仕様が増えつつあるので、余力があればカバー範囲の拡大もありか？
• 言語の入門
  • 導入に強く反対するものではありませんが、リファレンスの範疇を超えた「入門／解説記事」は個々人の考え方が大きく異なるため、複数名で共同編集する前提の cpprefjp では運用が難しいと感じています。
  • 類似事例として StackOverflow Documantation の 失敗 があり、本項目については消極的な意見です。

[faithandbrave]

単純なライブラリ仕様からは想像しづらい利用方法、単一クラス／関数ではなく組み合わせて使う複合的な機能群などの説明文や例示コードを増補していけるとベスト。

こちらは、どこに書けるといいとかありますか？
articleに分野ごとの階層を作ってそこで書くか、ライブラリごとのトップページに例を書いてアンカーをつけて各所に関連項目としてリンクを貼るとか、もしくは逆引きリファレンス的な階層がほしいか

ライブラリリファレンスの使いやすさ向上は、大きな目標というよりは都度やっていくイメージではありましたが、あらたな階層、あらたな仕組みがないとやりにくい作業もあると思いますので、この機会にしっかり相談していきましょう。

[faithandbrave]

導入に強く反対するものではありませんが、リファレンスの範疇を超えた「入門／解説記事」は個々人の考え方が大きく異なるため、複数名で共同編集する前提の cpprefjp では運用が難しいと感じています。

なるほど、たしかにそうですね。
Stackoverflowの事例紹介もありがとうございます。共同執筆だと、正確だが理解がむずかしいドキュメントになりがちなのですかね…。

一方で共同執筆の利点もあるかと考えました。それは、一定以上の正確性を期待できて安心して読めることが第一なのと、個性を出せない一方で、「私はこの説明では理解できなかったけど、ほかの文献でのこの説明だと理解できた」というのが提供されれば、理解のための複数の説明も提供できたりするのではないかと思いました。
そのために、たとえばタブだったり、折りたたみだったりといったページ上の表現を使える気がしています。

また、cpprefjpは現状でユーザーを育てることをしていません。イテレータとはなにか、コンテナとはなにかも、どこでも説明していないので、熟練したC++プログラマでなければcpprefjpを有効活用できないというのが懸念としてあります。
ですので、その育てる部分をほかに任せるよりも、用語説明、概念説明も含めて理解者を増やす活動をしてもよいのではないかと思いました。

[faithandbrave]

コンテナ要件、アロケータ要件、Clock要件みたいなのは、独自コンテナなどを作るときに必要となるので、要件を満たすコンテナの作り方の説明とともに、要件ページはあってもよさそうです。
/reference階層とは別に/requirement(s)とかを作るとかですかね。<requirement(s)>ヘッダができても大丈夫なように…。
それか/reference/lib-requiresとかハイフン区切りの階層を作れば標準ヘッダとは衝突しないはず。

[faithandbrave]

「ライブラリリファレンスの使いやすさ向上」として、関数・クラスの概要文章も強化したいです。

仕様を詳細に読まなくても概要とサンプルコードだけでなるべく使えてほしいので、時間をかけて一通りチェックして、概要文章を充実させていきたいです。

[faithandbrave]

• cpprefjp最初の完成のお知らせ - C++29の現在の仕様案まで追いつきました - Faith and Brave - C++で遊ぼう

cpprefjp最初の完成にあたり、ブログ記事を書きました。

[faithandbrave]

単一クラス／関数ではなく組み合わせて使う複合的な機能群

これは新たなカテゴリが必要になりそうなら、ある程度の数が必要になりそうですね。たとえばこんなページを書きたい、みたいなのを列挙してもらえると助かります。

[yohhoy]

ライブラリリファレンスの使いやすさ向上は、大きな目標というよりは都度やっていくイメージ

おっしゃる通り、実態としては個別ページでの改善作業を想定していました。

こちらは、どこに書けるといいとかありますか？
articleに分野ごとの階層を作ってそこで書くか、ライブラリごとのトップページに例を書いてアンカーをつけて各所に関連項目としてリンクを貼るとか、もしくは逆引きリファレンス的な階層がほしいか

特定ヘッダにのみ関連するトピックなら reference/ヘッダ/ 以下も候補になりえますが、将来バージョンで複数ヘッダ横断に拡張されるケースも出てきそうで、現行ルール通り article/ 以下が無難かなぁと考えています。

---

イテレータとはなにか、コンテナとはなにかも、どこでも説明していないので、熟練したC++プログラマでなければcpprefjpを有効活用できないというのが懸念としてあります。
ですので、その育てる部分をほかに任せるよりも、用語説明、概念説明も含めて理解者を増やす活動をしてもよいのではないかと思いました。

上記方針には賛成です。現行 cpprefjp ライブラリリファレンスは共通的・抽象度の高い概念の説明ページを持たないことが多いので、利用者にとっても有用だと思います。

個人的には cpprefjp に「C++言語を用いたプログラミング入門」的な記事を増やすことには弱い否定意見ですが、「cpprefjpを読み解く＝C++ライブラリ利用のための前提知識説明」的な記事には賛同です。

---

単一クラス／関数ではなく組み合わせて使う複合的な機能群
これは新たなカテゴリが必要になりそうなら、ある程度の数が必要になりそうですね。たとえばこんなページを書きたい、みたいなのを列挙してもらえると助かります。

現状のヘッダリストをみて思いついた範囲で列挙してみました（書きたい、訳ではないですｗ）

• 各種コンテナの特徴比較 : コンテナ選択時の参考情報として
• アルゴリズム・イテレータ・レンジ（＋ジェネレータコルーチン）の大まかな関連
• ストリーム関連ヘッダ/クラスの関係性、print／format系への拡張
• スレッド同期プリミティブの概要一覧 : 機能選択時の参考情報として
• 実行制御ライブラリ(std::execution)

リストアップしてみると、実質的には逆引きリファレンスになっていますね。どちらかといえば利用者からのフィードバックベースで考えた方が良いのかもしれません。

[faithandbrave]

「前提知識としてこちらも合わせてお読みください」みたいなページが必要だと感じますね。
そうだとしたら、現状のページ末尾の関連項目リンクとはまた別で、ページ先頭の方にリンクを列挙することを考えてもいいかもしれません。

そのうえで、こういった概念説明的なページはどこに置くべきか…それ自体もまたリファレンス、もしくはリファレンスを読むための前提知識なので、articleよりは別な階層がいいのかも、と漠然と思いました。
用語集とも違いますし、逆引きリファレンスは「〜を作るにはどうすれば」には適してしますが「〜を知りたい」だとまた違う気もします。