ボレロ村上 - ENiyGmaA Code

中3女子です。

Sprout のドキュメントを書いている


中3女子です。

現在、Sprout C++ Libraries のドキュメントを書いている最中だ。
ついでに GitHub Pages にプロジェクトページも用意した。
http://bolero-murakami.github.io/Sprout/


これまで Sprout のドキュメントは、乏しいというか纏まった形のものが殆どなかった。
あるものといえば自分や一部の尊敬すべきconstexpr愛好者である Sprout ユーザーの書いたブログ記事くらいだった。
Wiki の形で書きかけて放置したままのものもあるが、考えてみれば当然のことに、全般的な詳細を理解している者が開発者の自分しか居ないわけだから、Wikiのシステムを使う意味が全くなかった。
Sprout ユーザーのブログを読むと自分が一度も解説したことのない機能を使っていたりして、おそらくソースを直に読んで理解したのだろうと考えると頭の下がる思いである。
これもひとえに、まともにドキュメントを書いてこなかった自分の不徳の致すところだ。


そもそも、自分はドキュメントあるいはリファレンスというものを書く習慣がなかったし、その訓練もしたことがない。
もちろん実装や設計に当たっては事前条件や型制約や計算量を可能な限り厳密に考慮しているし、そうでなければ中3女子はやっていられない。
しかしながら、多人数開発したりライブラリを万人向けの成果物として公開したこともなかったし、何より完全な自己満足の趣味の領域であるから、そうしたことを他人と共有する必要性に迫られることがなかった。
それに、ドキュメントを書くよりも新しい機能を考えてコーディングする方がずっと楽しいのだから。(これは大半のホビープログラマに同意を貰えると思う)

動機

さて、今回あらためてドキュメントを書こうと決意した理由はと言えば2,3ほどある。
一つは、Sprout ライブラリの Boost 入り提案を考えるようになったためだ。
Boost 入りには当然のことながらドキュメントが無ければ話にならない。また、ドキュメント自体の品質も要求される。
例えば関数とそのシグネチャを箇条書きしたようなものでは駄目で、少なくともC++規格書の標準ライブラリ記述部分程度には詳細かつ厳密でなければならない。
そしてこれも当たり前だが、英語で書かなければならない。
英語は苦手だ。苦痛だ。
自分の英語力は中3女子レベルであって、専門用語を交えた間違いのない英文をイチから捻り出すことなどできないから、専ら Google 翻訳とC++規格書や Boost のドキュメントからのパクリに頼っている。
読んでみて「なんてみじめであわれな英語」と憐れんでくれる有志がもしおられたら、Pull Request はいつでも受け付けておりますゆえ。


もう一つは、やはりちゃんとしたドキュメントを提供しなければという義務感がある。
というのも、地道な開発と良心的なconstexpr愛好者の存在のおかげあってか、Sprout の知名度も少しずつ上がってきたように思う。
そのような中で、あまりに不親切な状態を放置しておくのは忍びないし、それにドキュメントが整っていればもっとユーザーが増えるのではという打算もある。
また、最近では英語圏の人間からの反応もごくまれに見かける。
それもまた英語で書くことの動機付けになっている。
(何しろ英語ネイティブスピーカーは自分がマジョリティだと自覚している故にものぐさだから、日本語で書かれた情報をわざわざ労力を割いて読もうとはしないだろう)


さらに一つ付け加えるなら、constexpr本のためもある。
なぜなら、constexpr本の執筆にあたっては Sprout の成果がその中心の一つとなる。(例えば Modern C++ Design における Loki のように)
一度本にしてしまえば、そこに記載されたコードが実際にコンパイルできないということになってはならないから、Sprout のバージョンをどこかの時点で固定しなければならない。
これまで Sprout のバージョニングというものはしておらず、常に開発版という状況だ。細かな仕様など常に更新されうる状態にある。
これをどこかの時点で固定するわけだが、曖昧な仕様がないか実装漏れが無いかなど一度総浚えして確認する必要があり、その為にもドキュメントを纏めることは重要である。
とはいえ、ドキュメントを書く時間の分、本書の執筆は止まることになるが、それはもうトレードオフと考えるしかない。

ツール

ツールには Sphinx というものを使うことにした。
Boost の QuickBook などはどうも取っつきにくく日本語情報があまりに少なすぎるので断念した。
Sphinx は人に薦められたものだが、これがなかなか素晴らしい。
コマンド一つでフォルダ分けした構造を追ってさくっとHTMLにビルドしてくれるのも良いし、TeX が書けるのも良いし、何より標準で使えるテーマがそれなりにクールだ。
不満と言えば今のところは、reST 記法でテーブルを書くのにインデント合わせがいささか面倒な点くらいだ。

進捗その他

現状、algorithm(non-modifying)array を一通り書き終わり、いま string を書き進めているところだ。
string はかなり苦痛だ。
メンバ関数も非メンバ関数無意味なほどバリエーションが多すぎる。これは一種の拷問だ。
まあ、とはいえこれは時間さえかければ何とかなる類なので大きな問題ではないだろう。
あらためて一覧を見てみると全体量があまりに多いので、darkroom や compost のようなニッチなライブラリは後回しになるだろうと思う。


書く上での方針としては、cpprefjp と同じくすべての詳細ページにサンプルコードを載せることと、すべての constexpr 関数に再帰深度のオーダーを載せることくらいだろうか。
とくに再帰深度のオーダーは非常に重要だし、中3女子としてマストな嗜みである。


アドバイスや要望などあればぜひ Twitter やコメント等で受け付けるのでお願いしたい。