JSDoc 1.9.9.2 を使ってみて大事だなと思ったこと

JSDoc をやっと真面目に使ってみた。実際に使ってみてハマったところを取り上げていく。基本的な使い方は自分で調べるなり試行錯誤するべし。

なお、以下はバージョン 1.9.9.2 について書いている。時間の経過とともにおかしな内容になっていく可能性大なので注意されたし。あと日本語のコメントは試してないんでどうなるか知らない。

正しく書く

値を取る attribute で値を書いてない1など、構文的に正しくないときに、よく HTML::Template の方でエラーを吐いて止まる。phpDocumentor みたいにエラーレポートは作ってくれないし、HTML::Template 段階でのエラーってことは当然パーサが吐いてるわけはなく、どこの何の記述(あるいは記述不足)がエラーなのかさっぱり分からないので、あとでまとめてドキュメントを生成するのではなく、こまめに作るようにした方がよさげ。

書き方は JSDoc のサイトにもあるけど、細かいものは JavaDoc のものを探してくるといい感じかも。

コンストラクタの書き方

きちっと対応しているのは

function Object() {
  ..
}

のみっぽい。

var Object = new function() {
  return function() {
  };
};

はコンストラクタは解釈できるが、中のメンバ変数(JSDoc の出力では Field ってやつ)が解釈できなかった。

あとこのコンストラクタ関数のコメントの中に @constructor を書いておいた方がよい。書かないと Field の解釈に失敗しやすいみたい。

フィールド(メンバ変数)の書き方

JavaScript 的には単にコンストラクタで初期化されるプロパティなんだと思うんだけど、まぁ要するに

function Constructor() {
  this.prop1 = 'foo';
  this.prop2 = undefind;
  this.prop3;
}

のところ。中身のない状態で初期化するのは 3 ではなく 2 の方法、つまり明示的に undefined をセットする方法が正しい。JSDoc 的には。

明示してないものは Field Summary にも当然 Field Detail にも現れない。

メソッドにも @type を

@return に型を書いてもメソッドの型としては認識してくれない。ちょっと面倒だけど、

/**
 * @type   boolean
 * @return boolean
 */
method: function() {
}

にしないといけない。まぁ気にしなきゃいいって話もあるかもしんないけど、それだと Method Summary のところで戻り値の型が分からないのよね。

うっかり : が書けない。

/**
 * summary
 *
 * detail: foo bar hoge
 */
method: function() {
}

てなことをすると

detail: foo

の部分が

Class.prototype.detail = foo;

に展開され、結果として

Class.prototype.detail = foo;bar hoge

になる。

※ ただ、必ずなるかというとそうでない場合もある。よく分からん。

組み込みオブジェクトの拡張には @addon

@member を書くと二重に出力されるのでうざい。例えば以下のような感じ。

/**
 * @addon
 */
Array.prototype.include = function() {
}

ただ、ないとエラーになっていたような気がしていたのに、なくてもそのまま通ったりもする。あっれ?

メソッドの書き方

できないと思っていたが、

Class.prototype = {
  method: function() {
  }
}

の書き方も

Class.prototype.method = function() {
}

の書き方も両方いけた。

夜中は嘘書いてごめんなさい。

感想として

JavaScript の構文解釈の精度は意外と悪くないと言ったら失礼だけど、自分の書き方だとほぼ思った通りに解釈してくれる。ただそのうえでコメントの記述がその後押しをしていて、正しくコメント付けするとよりよいドキュメントが生成できる、という感じ。まぁコメント付けは正しい方がいいのは言うまでもないことなんだけど、phpDocumentor のエラーレポートみたいなものは期待できないので、若干人間の側の負荷が高いかなって気はする。

あと、こまめにドキュメント生成しろって辺りか。複数のファイルを一気に処理するとどこでおかしなことになってるのかなかなか分からないんで。

最後に、これは使えると思う。

  1. 例えば @return のあとを空にしちゃうとか 

More

Categories

Tool 日々 Web Biz Net Apple MS ことば News Unix howto Food PHP Movie Edu Community Book Security Text TV Perl Ruby Music Pdoc 生き方 RDoc ViewCVS CVS Rsync Disk Mail FreeBSD Cygwin PDF Photo Zebedee Debian OSX Comic Cron Sysadmin Font Analog iCal Sunbird DNS Linux Wiki Emacs Thunderbird Sitecopy Terminal Drawing tDiary AppleScript Life Money Omni PukiWiki Xen XREA Zsh Screen CASL Firefox Fink zsh haXe Ecmascript PATH_INFO SQLite PEAR Lighttpd FastCGI Subversion au prototype.js jsUnit Apache Trac Template Java Rhino Mochikit Feed Bloglines CSS del.icio.us SBS qwikWeb gettext Ajax JSDoc Rails HTML CHM EPWING NDTP EB IE CLI ck ThinkPad Toy WSH RFC readline rlwrap ImageMagick epeg Frenzy sysprep Ubuntu MeCab DTP ERD DBMS eclipse Eclipse Awk RD Diigo XAMPP RubyGems PHPDoc iCab DOM YAML Camino Geekmonkey w3m Scheme Gauche Lisp JSAN Google VMware DSL SLAX Safari Markdown Textile IRC Jabber Fastladder MacPorts LLSpirit CPAN Mozilla Twitter OpenFL Rswatch ITS NTP GUI Pragger Yapra XML Mobile Git Study JSON VirtualBox Samba Pear Growl Mercurial Rack Capistrano Rake Win RSS Mechanize Sitemaps Android JavaScript Python RTM OOo iPod Yahoo Unicode Github iTunes God SBM friendfeed Friendfeed HokuUn Sinatra TDD Test Project Evernote iPad Geohash Location Map Search Simplenote Image WebKit RSpec Phone CSV WiMAX USB Chrome RubyKaigi RubyKaigi2011 Space CoffeeScript Nokogiri Hpricot Rubygems jQuery Node GTD CI UX Design VCS Kanazawa.rb Kindle Amazon Agile Vagrant Chef Windows Composer Dotenv PaaS Itamae SaaS Docker Swagger Grape WebAPI Microservices OmniAuth HTTP 分析基盤 CDN Terraform IaaS HCL Webpack Vue.js BigQuery Middleman CMS AWS PNG Laravel Selenium OAuth OpenAPI GitHub UML GCP TypeScript SQL Hanami Develop Document Jekyll