八発白中

技術ブログ、改め雑記

Day 9: Quickdocs

advent-calendar/2016

これは 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 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ではファイル毎に、出現した順番でドキュメントを並べています。

f:id:nitro_idiot:20161209080154p:plain

優れたプログラマが書いたと仮定するならば、ファイルに出現する順番にも意図があるはずです。上のほうにあればより重要だったり、隣り合う関数定義には関連性があったり。そういった意図を尊重するため、どう表示するか迷ったら「極力コードを尊重する」という方針で開発者の意図がユーザに伝わるようなドキュメントを生成する工夫をしています。

さらなる機能

Quickdocsはドキュメントを閲覧するだけでなく、必要なライブラリを探せるというWebサイトでもありました。そういった用途で重要なのは、このライブラリは使っても大丈夫か、信頼性はあるかという情報です。

Quickdocsには独自の機能として、依存するライブラリと依存されているライブラリを一覧できる機能があります。

たとえばClackの場合は36の依存ライブラリがあり、15のライブラリに依存されているようです。

f:id:nitro_idiot:20161209010404p:plain

依存されているライブラリが多ければそれなりに市民権を得ていると言えます。

また、Quicklisp badgesというREADMEに埋め込む用のバッジもあります。

Quicklispに登録されている場合は登録されているdistの最新バージョンが Quicklisp のように表示されます。登録されていない場合はQuicklispのように表示されます。

これはライブラリがきちんとアップデートされているか、開発が続いているかということを確認するのに役立ちます。

この点はまだできる余地はあるとは思いますが、簡単にできるものだけ手を付けているといった状況です。

おわりに

QuickdocsはGitHubで公開されています。

明日のアドベントカレンダーは10日目のSxQLについてです。お楽しみに。

*1:Pythonをやっている方は馴染み深いかもしれませんが、関数の中に文字列を書くと関数シンボルと結びつき、documentation関数でアクセスすることができます。このドキュメント文字列は変数やクラスやスロットはもちろん、パッケージなどにも書くことができます。