JavaScriptMVC でドキュメントを生成

JavaScriptMVC で作成したアプリケーションの API ドキュメンテーションを生成します。

この記事の続きです。

• JavaScriptMVC - 概要 (2011年8月25日)
• JavaScriptMVC を使ってみる (2011年8月26日)
• JavaScriptMVC でテストを実行 (2011年8月27日)

API ドキュメントの生成

JavaScriptMVC でドキュメントを生成するには documentjs を使います。

cookbook アプリケーションのドキュメントを生成します。

$ ./documentjs/doc cookbook
PROCESSING SCRIPTS

  cookbook/controllers/recipe_controller.js
  cookbook/cookbook.js
  cookbook/models/recipe.js
  cookbook/resources/example.js
  cookbook/scripts/build.js
  cookbook/scripts/clean.js
  cookbook/test/funcunit/recipe_controller_test.js
  cookbook/test/qunit/recipe_test.js

GENERATING DOCS -> cookbook/docs

Using default page layout.  Overwrite by creating: cookbook/summary.ejs

生成されたものは cookbook/docs.html で確認できます。 Javadoc みたいな感じです。

@Static と @Prototype は明示的に記述しておくと良さそうです。 また、 index.json を生成できるようにすると、トップページコンテンツを配置できるようです。

終わりに

サンプルアプリケーションの API ドキュメントを生成しました。 メソッドの一覧を確認して、冗長なインターフェイスを作ってしまっていないか確認できます。

また、引数と戻り値を記述しておくと、しばらくしてからコードを見直すときにもキャッチアップしやすいでしょう。 オブジェクトを渡すのかコールバックを渡すのか、戻り値は undefined なのかメソッドチェーンでつなげるのか。 確認すべきポイントは人それぞれにあるでしょうが、一貫性のある API だと間違いが少なくなりそうですね。

次は、ソースコードを連結して、プロダクション用のファイルを生成します。