OpenSocialとJSDoc
本職をそっちのけで、ちょっと現実逃避。
Ajax全盛時代の昨今では、記述されるJavaScriptコードの量も半端じゃないので、メンテナンスするためのドキュメントも重要になってきます。OpenSocial JavaScript APIに関しても、バージョンが上がるにつれて大きくなってきているため、 API Referenceを追うのも大変です。
Javaにおいては、最初からJavadocと呼ばれる機構があり、ソースコード中のAPI Referenceを自動生成して共有するという文化は極々自然です。JavaScriptにおいても、JSDocと呼ばれるJavaScript版Javadocがあります。
[JSDoc Homepage - JavaScript Documentation Tool]
例えば、
/**
- ホゲクラスです。ホゲることができます。
- @type Object
- @class Hoge */ Hoge.prototype = new Object();
なんて感じで、ドキュメントを付けていくことが可能です。
さて、このようにしてJSDoc仕様でコメントを記述しておくことによって、EclipseのJavaScript Development Toolsにてリッチな編集が可能となります。JSDTは、JSDoc仕様で書かれた内容に基づいて、コードの補完をしてくれたりする、とても便利なPlug-inです。
しかし、
-
ドキュメントを出力するためのJSDocタグの記述
-
JSDTにて補完機能を生かすためのJSDocタグの記述
では、記述レベルが違うっぽく、OpenSocialの仕様ページにあるjsファイルに記述されているレベルでは、ほぼ解析してくれません。例えば、@returnがほとんど書かれていないため、流れるようにコーディングすることもできません。
頑張って書き直して、 OSDEで補完機能が効くようにしてみたいと思います。
