Repository navigation
cpprefjp完成のお知らせと、これからの相談 #1755
Description
Activity
cppreferenceで嫌いな点は、重要な情報が雑音と区別がつかないことです。
std::shared_ptrのコンストラクタ#8は他のどれかと大差ないように見えますが、aliasing constructorと呼ばれる非常に重要なもので、衝撃的です。cpprefjpに対してではないですが、たしかに、と思ったポストです。
リファレンスなのでなかなか「これが重要な仕様！」とは書きにくいですが、重要な仕様のためのサンプルコードやコード片は追加であってもいいのかなと思います。追加のサンプルコードで書きやすいのは、C++xxからこういうコードが書けるようになった、ですかね。
それと、従来のこういう書き方は (cpprefjpとして) 推奨しない、とか。std::equalの3引数版は長さチェックされなくてクラッシュする場合があるので、推奨しない、とか (なぜかdeprecatedにならないけど、4引数版を推奨したい)。C++26（＆現時点のC++29WD）までの追従、おつかれさまでした 🎉
個人的にはcpprefjpに求める優先度・重要度を下記順で考えています。
- ライブラリリファレンスの使いやすさ向上
- 単純なライブラリ仕様からは想像しづらい利用方法、単一クラス／関数ではなく組み合わせて使う複合的な機能群などの説明文や例示コードを増補していけるとベスト。
- 言語機能のリファレンス
- 「C++に関するリファレンスサイト」という立ち位置的には、言語機能についても手を広げるのはあり。
- C言語対応
- C独自／C++未導入の仕様が増えつつあるので、余力があればカバー範囲の拡大もありか？
- 言語の入門
- 導入に強く反対するものではありませんが、リファレンスの範疇を超えた「入門／解説記事」は個々人の考え方が大きく異なるため、複数名で共同編集する前提の cpprefjp では運用が難しいと感じています。
- 類似事例として StackOverflow Documantation の 失敗 があり、本項目については消極的な意見です。
- ライブラリリファレンスの使いやすさ向上
単純なライブラリ仕様からは想像しづらい利用方法、単一クラス／関数ではなく組み合わせて使う複合的な機能群などの説明文や例示コードを増補していけるとベスト。
こちらは、どこに書けるといいとかありますか？
articleに分野ごとの階層を作ってそこで書くか、ライブラリごとのトップページに例を書いてアンカーをつけて各所に関連項目としてリンクを貼るとか、もしくは逆引きリファレンス的な階層がほしいかライブラリリファレンスの使いやすさ向上は、大きな目標というよりは都度やっていくイメージではありましたが、あらたな階層、あらたな仕組みがないとやりにくい作業もあると思いますので、この機会にしっかり相談していきましょう。
導入に強く反対するものではありませんが、リファレンスの範疇を超えた「入門／解説記事」は個々人の考え方が大きく異なるため、複数名で共同編集する前提の cpprefjp では運用が難しいと感じています。
なるほど、たしかにそうですね。
Stackoverflowの事例紹介もありがとうございます。共同執筆だと、正確だが理解がむずかしいドキュメントになりがちなのですかね…。一方で共同執筆の利点もあるかと考えました。それは、一定以上の正確性を期待できて安心して読めることが第一なのと、個性を出せない一方で、「私はこの説明では理解できなかったけど、ほかの文献でのこの説明だと理解できた」というのが提供されれば、理解のための複数の説明も提供できたりするのではないかと思いました。
そのために、たとえばタブだったり、折りたたみだったりといったページ上の表現を使える気がしています。また、cpprefjpは現状でユーザーを育てることをしていません。イテレータとはなにか、コンテナとはなにかも、どこでも説明していないので、熟練したC++プログラマでなければcpprefjpを有効活用できないというのが懸念としてあります。
ですので、その育てる部分をほかに任せるよりも、用語説明、概念説明も含めて理解者を増やす活動をしてもよいのではないかと思いました。コンテナ要件、アロケータ要件、Clock要件みたいなのは、独自コンテナなどを作るときに必要となるので、要件を満たすコンテナの作り方の説明とともに、要件ページはあってもよさそうです。
/reference階層とは別に/requirement(s)とかを作るとかですかね。<requirement(s)>ヘッダができても大丈夫なように…。
それか/reference/lib-requiresとかハイフン区切りの階層を作れば標準ヘッダとは衝突しないはず。「ライブラリリファレンスの使いやすさ向上」として、関数・クラスの概要文章も強化したいです。
仕様を詳細に読まなくても概要とサンプルコードだけでなるべく使えてほしいので、時間をかけて一通りチェックして、概要文章を充実させていきたいです。
cpprefjp最初の完成にあたり、ブログ記事を書きました。
単一クラス／関数ではなく組み合わせて使う複合的な機能群
これは新たなカテゴリが必要になりそうなら、ある程度の数が必要になりそうですね。たとえばこんなページを書きたい、みたいなのを列挙してもらえると助かります。
ライブラリリファレンスの使いやすさ向上は、大きな目標というよりは都度やっていくイメージ
おっしゃる通り、実態としては個別ページでの改善作業を想定していました。
こちらは、どこに書けるといいとかありますか？
articleに分野ごとの階層を作ってそこで書くか、ライブラリごとのトップページに例を書いてアンカーをつけて各所に関連項目としてリンクを貼るとか、もしくは逆引きリファレンス的な階層がほしいか特定ヘッダにのみ関連するトピックなら
reference/ヘッダ/以下も候補になりえますが、将来バージョンで複数ヘッダ横断に拡張されるケースも出てきそうで、現行ルール通りarticle/以下が無難かなぁと考えています。
イテレータとはなにか、コンテナとはなにかも、どこでも説明していないので、熟練したC++プログラマでなければcpprefjpを有効活用できないというのが懸念としてあります。
ですので、その育てる部分をほかに任せるよりも、用語説明、概念説明も含めて理解者を増やす活動をしてもよいのではないかと思いました。上記方針には賛成です。現行 cpprefjp ライブラリリファレンスは共通的・抽象度の高い概念の説明ページを持たないことが多いので、利用者にとっても有用だと思います。
個人的には cpprefjp に「C++言語を用いたプログラミング入門」的な記事を増やすことには弱い否定意見ですが、「cpprefjpを読み解く＝C++ライブラリ利用のための前提知識説明」的な記事には賛同です。
単一クラス／関数ではなく組み合わせて使う複合的な機能群
これは新たなカテゴリが必要になりそうなら、ある程度の数が必要になりそうですね。たとえばこんなページを書きたい、みたいなのを列挙してもらえると助かります。現状のヘッダリストをみて思いついた範囲で列挙してみました（書きたい、訳ではないですｗ）
- 各種コンテナの特徴比較 : コンテナ選択時の参考情報として
- アルゴリズム・イテレータ・レンジ（＋ジェネレータコルーチン）の大まかな関連
- ストリーム関連ヘッダ/クラスの関係性、
print／format系への拡張 - スレッド同期プリミティブの概要一覧 : 機能選択時の参考情報として
- 実行制御ライブラリ(
std::execution)
リストアップしてみると、実質的には逆引きリファレンスになっていますね。どちらかといえば利用者からのフィードバックベースで考えた方が良いのかもしれません。
「前提知識としてこちらも合わせてお読みください」みたいなページが必要だと感じますね。
そうだとしたら、現状のページ末尾の関連項目リンクとはまた別で、ページ先頭の方にリンクを列挙することを考えてもいいかもしれません。そのうえで、こういった概念説明的なページはどこに置くべきか…それ自体もまたリファレンス、もしくはリファレンスを読むための前提知識なので、articleよりは別な階層がいいのかも、と漠然と思いました。
用語集とも違いますし、逆引きリファレンスは「〜を作るにはどうすれば」には適してしますが「〜を知りたい」だとまた違う気もします。ひとまず直近の方針案です。
- 「概念・前提知識ガイド」として
guide/階層を新設。リファレンスを読み解くための知識・考え方などは、ここで説明する。yohhoyさんに案をいただいた5つも、ここに置けるかと思います。- リファレンスの各ページには、概要の下に「## 概念・前提知識」セクションを設けて、そこにguide階層以下のページへのリンクを列挙する
- 無秩序化するとよくないので、guide / articleに新しいページを作るときはまずIssueで相談するのがいい気がします
- まずはたたき台を作ったあと雛形化していきたいです
- ライブラリ要件として
requirements/階層を新設。コンテナ要件、アロケータ要件、イテレータ要件などのほか、当面残りそうなCpp17EqualityComparableなどの要件もそこに書く- コンテナ要件、アロケータ要件などは、コンテナ・アロケータを作るための最小実装や、ユーザーがどのように実装すればいいかの解説を入れる
それらが一通り落ち着いたタイミングで、言語リファレンス・入門・C言語対応などを検討する。
言語リファレンスについては現時点でyohhoyさんとの優先順位が一致しているので、追加意見がなければそこから話を進める。- 「概念・前提知識ガイド」として
2週間経って追加のコメントがなかったので、一旦この方針で進めてみようかと思います。
guide階層とrequirements階層を作ったらこのissueを閉じます。
C++29までの作業が一通り完了し、C互換ライブラリ・iostream・locale周りも必要なものは一通りおわりました。
これで、cpprefjpが当初から目指していた範囲としては、一旦完成となります。
まずはここまでご尽力いただいた方々、ありがとうございます。
cpprefjpはC++での開発をするにあたって必要不可欠なインフラへと成長してこれたのは、みなさんがさまざまな視点で貢献くださったからだと思います。
cpprefjpの今後に向けてご相談
さて、今後に向けてですが、AIの力も借りることで執筆スピードが向上し、検証もしやすくなったので、cpprefjpが扱う範囲をさらに拡大していけると考えています。
とくにcpprefjpは言語側が弱いというのはさまざまなところで言われているので、そのあたりをカバーしていければと思っています。
またほかにもやりたいことはいろいろでてくるかと思いますので、やりたいことがあれば実現させるかはわからないですが、書いていってほしいです。
また、優先的に対応する順序も決めていきたいです。
まず私が考える優先順位を書きます。
1. 言語の入門
2. 言語機能のリファレンス
3. ライブラリリファレンスの使いやすさ向上
shared_ptrのaliasing constructorとかは、説明はありますがさらっとしているので、独自した例とともに説明できるといいかなと0LLみたいな) とかも載せられるといいかなと思っています4. C言語対応