memorycraft wiki

SproutCore ドキュメント翻訳トップ

Docツール

SproutCore?のビルドシステムにはJSDocをベースにしたビルトインのリファレンスドキュメンテーションツールが付属しています。SproutCore?自身やあなたのアプリケーションでの自動ドキュメント生成を行うために使用できます。リファレンスドキュメンテーションはあなたのチームのメンバーに、自分の書いたクラスのコードの使い方をすばやく学習してもらうのに非常にすぐれた方法です。

なぜドキュメントを含めるのか

もし世の中に公開したいフレームワークを書いている場合、インラインドキュメンテーションは有効です。しかしあなたの独自のアプリケーションにインラインドキュメントを書くのはなぜでしょうか？さて、そこにはいくつかのとても大事な理由があります。

1. チーム内での共有 それがたとえ今日書かれたアプリケーションであっても、ドキュメントはあなたが書いたものを、後日あなたやチームメイトが理解するのに確実な助けとなります。
2. コードの熟慮 自分のAPIをドキュメント化することは、記述したメソッドをじっくり検討することの助けになります。何を行うか、どんな引数を受け付けるか、何を返すか、エラーの条件は？ ドキュメントを書いた方が良いコードをシンプルにかけます。
3. APIの検索 なんと言ってもここで説明する書式をつかうことで、ビルトインのシンボル検索もできるSproutCore?ドキュメンテーションビューで、自分の記述したドキュメントを引き出し、使用することができます。これはあなたのプロジェクトが大きくなったときに、あなたや他のチームメイトの間で重複したコードを避けるための非常に大きな助けになります。

ドキュメントのビルドと閲覧

SproutCore?のドキュメントを見るには、開発サーバーが起動していることを確認し、http://localhost:4020/sproutcore/-docs を閲覧してください。ドキュメントページを初めて訪れると、ドキュメントはまだ生成されていないのでなにも表示されていません。ドキュメントを生成するには左下の“Rebuild Docs” をクリックします。

IMPORTANT:

SproutCore?は実行に時間がかかるために、自動的にドキュメントを生成しません。コードの変更を行い、最新のドキュメントを見たい場合は、その都度DocTool?の“Rebuild Docs”をクリックしてください。

あなたのつくったクライアントアプリやフレームワークのURLに"/-doc"をつけることで、そのドキュメントを見ることができます。たとえば開発モードで あなたのアプリケーションを http://localhost:4020/contacts でロードしたとすると、ドキュメントは http://localhost:4020/contacts/-docs で確認できます。

初めてクライアントアプリのDocツールを訪れたら、左下の“Rebuild Docs”ボタンをクリックします。コードを変更したあと最新の状態を更新したい場合は、都度 “Rebuild Docs” ボタンをクリックします。

ドキュメントの記述

SproutCore?のDocツールはオープンソースのJSDoc Toolkitをベースにしています。あなたのドキュメントを確認するツールを取得するために、JSDocのルールに従う必要があります。加えてSproutCore?プロジェクトはあなたのドキュメントの記述をするときに簡潔でわかりやすいドキュメント化の助けになるベストプラクティスを確立しました。

クラスのドキュメント化

作成したそれぞれのクラスでは最初にそのクラスの目的と使い方の説明を記述します。SproutCore? のジェネレーターは自動的にクラス新規クラステンプレートを作成し、クラスドキュメントを記載するスペースも作ってくれます。必要な部分を埋めてください。以下に一般的なクラスのドキュメントを記します。

 /** <-- Two * are required.  Do not start each line with an asterisk.

 @class  <-- IMPORTANT: must be at the top of your declaration

 v-- Provide a 1 paragraph overview of the class
 A Timer executes a method after a defined period of time.  Timers are
 significantly more efficient than using setTimeout() or setInterval()
 because they are cooperatively scheduled using the run loop.  Timers are
 also gauranteed to fire at the same time, making it far easier to keep
 multiple timers in sync.      

 v-- Add a section for each major task someone might perform with your class
 h2. Scheduling a Timer  <-- Use Textile to format text. Headings are h2.

 To schedule a basic timer, you can simply call SC.Timer.schedule() with
 a target and action you wish to have invoked:      

 {{{ <-- Wrap code examples in {{{ ... }}}
    var timer = SC.Timer.schedule({
      target: myObject, action: 'timerFired', interval: 100
    });
 }}}

 When this timer fires, it will call the timerFired() method on myObject.
 In addition to calling a method on a particular object, you can also use
 a timer to execute a variety of other types of code:

 v-- Use - for bulleted lists
 - If you do not pass a target object, then the action method will be passed,
   down the responder chain.
 - If you pass a string with a period in it for the action, it will be treated
   as a property path.
 - If you pass a function for the action, the function will be called in the
   content of the target.

 @extends SC.Object  <-- Add an @extends for each class or mixin you import
 @author Charles Jolley <-- Your name goes here
 @version 1.0
 @since version 1.0  <-- Can be omitted, but useful for frameworks
*/ [#caaa1a59]
SC.Timer = SC.Object.extend(
/** @scope SC.Timer.prototype */ { <-- IMPORTANT: @scope required
...
});

プロパティのドキュメント化

プロパティはget() と set() のメソッドでアクセスされる、静的な値か計算プロパティです。これらのプロパティはドキュメントページのFieldsセクションに記載されます。これはプロパティのドキュメントの書き方です。

 /** <-- Two * are required.  Do not start each line with an asterisk.

   v-- One sentence summary.  Appears in tooltip and at the top of a field
       description.
   The target object whose method will be invoked when the time fires.

   v-- Add any extended discussion with more details of the property in a
       separate paragraph.  This will appear in the "Discussion" section of
       the docs.
   You can set either a target/action property or you can pass a specific
   method.

   @type {Object} <-- Specify the type of objects that belong in the field.
   @field <-- IMPORTANT: Required by JSDoc
 */
 target: null,

アンダースコアで始まるプロパティはprivateプロパティなので、ドキュメントには記載されません。

NOTE:

SproutCore?に含まれる現行バージョンのJSDocでは、不適切なことに計算プロパティがFieldsではなくMethodsのページに記載されます。これは次期バージョンのJSDocで改善される予定で、準備が整い次第SproutCore?に組み込まれます。新しいバージョンのJSDocに対応できるように計算プロパティも上記のフォーマット常に使用するようにしてください。

メソッドのドキュメント化

メソッドは他のコードの実行や上書きをするための関数です。これらのメソッドはドキュメントページではMethodsセクションに記載されます。以下がメソッドのドキュメントの書き方です。

 /** <-- IMPORTANT: Two * are required.  Do not start each line with an asterisk.

   v-- One sentence summary.  Will appear in tooltip and at top of method
     description
   Called whenever the view's innerFrame size changes.  You can override this
   method to perform your own layout of your child views.

   v-- Add any extended discussion here.  Appears in "Discussion" section.
   If you do not override this method, the view will assume you are using
   CSS to layout your child views.  As an optimization the view may not
   always call this method if it determines that you have not overridden it.

   This default version simply calls resizeWithOldParentSize() on all of its
   children.

   v-- One @param line for each param.  Name the property, type, and description
   @param oldSize {Size} The old frame size of the view.
   @returns {void} Nothing. <-- Return type and description.  Always include at least {void}
 */
 resizeChildrenWithOldSize: function(oldSize) {
 ...
 },

アンダースコアで始まるメソッドはprivateメソッドのため、ドキュメントには記載されません。

関連リンク

JSDoc Toolkit – SproutCore? のDocツールのドキュメンテーションエンジンのドキュメント

このページの原文

関連ページ

1. Memorycraft Wiki561日前
2. SproutCore ドキュメント翻訳561日前