これは fukamachi products advent calendar 2016の9日目の記事です。
今日はQuickdocsについて話します。珍しく今回はライブラリの話ではありません。
ドキュメント生成の歴史
2日目のClackの回でも少し触れましたが、Clackは単に完成物としてのプロダクトだけに留まらず、自動テストやドキュメントの完備にも力を入れていました。
Clackではアクセス可能なシンボルすべてとパッケージすべてにドキュメント文字列 *1を書きました。そしてリリース後にドキュメント文字列から閲覧可能なHTMLを生成するツール「clack-doc」を作りました。
clack-docは名前の通りClack専用のものとして作られ、のちにCavemanにも対応しました。適応ライブラリが限定的なのは、Clackが1ファイル1パッケージを前提にしたものであることや、ドット区切りの独特な階層パッケージ名なども意味のあるものとして解釈し、そういう分割単位でHTMLを表示したからです。
ドキュメントの不備
それから1年ほど経った頃、これでは不十分だなと感じ始めました。
少し脱線になりますが、ちょうど@hyotang666さんが問題意識として挙げていたので紹介します。
Common Lisp界のドキュメントは「すでにそれを知っている人にとっては充分だが、未だそれを知らざる人にとっては充分でない」というレベルにある、という印象が強い。
— sin (@hyotang666) 2016年12月8日
これはCommon Lispという言語がアプリオリに持つ病巣だという印象。 https://t.co/QO39mNfFKY
今日のツイートなのでまだ解決されていない根深い問題なのでしょう。これに対していくらか賛同の声もあるようです。
ただ、僕はこれに対する「自分さえわかればいい」という姿勢であるという考えは違うと思います。
Lispは文法が単純で生産性が高いため、チームを組む必要がなく、そのため「自分さえ分かればいい」というドキュメントが多い印象。 https://t.co/kl1UboTQdP
— sin (@hyotang666) 2016年12月8日
@hyotang666僕の推察では、単純に手が足りてないからです。コミュニティ自体が小さいからその点で他の言語と比較するのはフェアじゃないです。優先度の問題で手がつけられていないだけです。
— fukamachi (@nitro_idiot) 2016年12月8日
ドキュメントは欲しい、けれどそういった手間がかけられない、というのが実情だと思いますし、事実僕のライブラリの周りはそうです。
ドキュメントの整備が比較的優先度が低いのはおかしい、とかCommon Lisperは初心者のことを考えていないのではないか、という声も当然あるとは思います。
まあ、言ってしまえばそうです。Common Lispのコミュニティのリソースは他の人気言語に比べて圧倒的に少ないです。その少ないコミュニティリソースで今切望とされているのは、実は初心者ではなく開発者です。コントリビューターです。そして開発者ならば、ドキュメントがなくともコードを読んでパッチを送ってくれます。ドキュメントの整備よりも、プロダクトの開発と改善にリソースが全力投資されている、というのが実情ではないでしょうか。
最近は「Common Lispはライブラリが足りない」という声を聞かなくなってきました。ライブラリが足りないという問題に比べるとドキュメントが足りないという問題は少しマシなのかなと思っています。
けれどそういった中でも、せめて自動生成のドキュメントくらいはあってもよかろう。そういう意図で作られたのが「Quickdocs.org」です。
Quickdocsはドキュメントの生成ツールに留まらず、Quicklispに登録されているすべてのライブラリをパースしてドキュメントを自動生成し、それを同時にホスティングするというものです。
自動生成なのでライブラリの設計思想などはREADMEなどを見てもらわなければいけませんが、自動生成には更新のコストが低いという利点もあります。そのためQuickdocsは常に最新の状態を保つことができました。
Quickdocsの意義
当時にもドキュメント生成ツールやHTMLで閲覧可能なものはありました。
たとえばdocbrowser。REPLでロードして関数一つ呼び出すだけで、REPLにあるシンボルの一覧を表示するHTMLをlocalhostで見ることができます。
他にはCommon Lisp Documentation Search Engine。これはQuicklispに登録されているライブラリのシンボル名を検索できるWebサービスです。
これらとQuickdocsが異なる点は、Quickdocsは常に更新されていてどこからでもWebで同じ見た目で見られることです。
同じ見た目で見られるというのは重要です。ドキュメントを見る時にライブラリごとにドキュメントページの使い方を覚えるほど不毛なことはありません。同じ見た目と使い方であることは安心感も与えます。
さらにQuickdocsはAPIリファレンスの生成にも哲学があります。「コードは雄弁である」ということ。
以前までのCommon Lispのドキュメントはシンボルを集めてアルファベット順に羅列しただけです。これは検索するにはいいかもしれませんが、ざっとライブラリの全体像を把握したいというときには何が大事なのかわかりません。クラスとアクセサがまったく別のところに表示されているなども起こりうることです。
Quickdocsではファイル毎に、出現した順番でドキュメントを並べています。
優れたプログラマが書いたと仮定するならば、ファイルに出現する順番にも意図があるはずです。上のほうにあればより重要だったり、隣り合う関数定義には関連性があったり。そういった意図を尊重するため、どう表示するか迷ったら「極力コードを尊重する」という方針で開発者の意図がユーザに伝わるようなドキュメントを生成する工夫をしています。
さらなる機能
Quickdocsはドキュメントを閲覧するだけでなく、必要なライブラリを探せるというWebサイトでもありました。そういった用途で重要なのは、このライブラリは使っても大丈夫か、信頼性はあるかという情報です。
Quickdocsには独自の機能として、依存するライブラリと依存されているライブラリを一覧できる機能があります。
たとえばClackの場合は36の依存ライブラリがあり、15のライブラリに依存されているようです。
依存されているライブラリが多ければそれなりに市民権を得ていると言えます。
また、Quicklisp badgesというREADMEに埋め込む用のバッジもあります。
Quicklispに登録されている場合は登録されているdistの最新バージョンが 
のように表示されます。登録されていない場合は
のように表示されます。
これはライブラリがきちんとアップデートされているか、開発が続いているかということを確認するのに役立ちます。
この点はまだできる余地はあるとは思いますが、簡単にできるものだけ手を付けているといった状況です。
おわりに
QuickdocsはGitHubで公開されています。
明日のアドベントカレンダーは10日目のSxQLについてです。お楽しみに。