doccoとgrunt-doccoのごにょごにょについて

doccoという結構使いやすい*1ドキュメント生成ツールがあります。

これのgruntのpluginがあるのですが、これにまつわるもやもやについて

docco

doccoはコードの中にmarkdownを書いてインラインコメントアウトするとよしなにdocumentを生成してくれます。 0.6.2からpygmentsの依存がなくなったので使いやすくなりました。

ですが、0.6.0でメインであるdocco.document()の引数に大幅な変更が入り、追従できていない(今回の場合は、grunt-docco)のもあるみたいです。 具体的には、

  • 0.6.0まで
document = function(sources, options, callback) {
  • 0.6.0から
document = function(options){

使い方はほんとうに簡単で

# ## クラス名
# クラス説明
# ```
# 使い方
# ```
class Hoge
  # コンストラクタだよ
  # * @arg1: 引数です
  constructor: (@arg1)->

としておくだけです。

coffeeとjsだけではなく、languagesを見ると結構いろいろ使えるようです。

grunt-docco

これをgruntから使うためにgrunt-doccoというのがあるのですが、前述のとおり、docco側のapiの変更に追従できておらず、cssやらなんやらがイケてない感じでした。

引数の変更だけで簡単ではあるんですが、

document = function(options){

この中ではcallbackを受けないので、multitaskだと一個目しか評価されない!

で、docco側にも手が入って、master( not latest 0.6.2 on 2013/04/14)では、

document = function(options, callback){

となって、あとはこれが0.6.3として取り込まれればOKという状態です。 @neocotic ++

まとめ

doccoはファイルをまとめて渡すとそれらの間に相互のリンクを張ってくれるんですが、gruntでmultitaskで指定した時には、ファイル間だけじゃなくてそれぞれのtaskの間にもリンクを張ってくれると嬉しいと思います(あー、いつかやります

Makefile => Cakefile => Grunt と流れて来ましたが、自分の中でこれかなぁってのが定まってきました。GruntかわいいよGrunt

*1:quick-and-dirty documentation generator