AddHelp

自作ライブラリに Help.js のサポートを組み込む

GitHub にホストしている自作ライブラリに Help.js のサポートを組み込む方法を説明します。

ここで例にする Foo.js と、Foo.js の原型となる Foo.before.js は Help.js の test/example 以下に同梱されています。

ここでは、Help.js をサポートするために必要なコードを Foo.before.js に対して順を追って追加していきます。

    // Foo.before.js

    (function(global) {

    // --- define ----------------------------------------------
    // --- variable --------------------------------------------
    // --- interface -------------------------------------------
    function Foo(name) {
        this._name = name;
    }

    Foo.name = "Foo";
    Foo.prototype.name  = Foo_name;  // Foo#name():String
    Foo.prototype.isFoo = Foo_isFoo; // Foo#isFoo():Boolean
    // --- implement -------------------------------------------
    function Foo_name() {
        return this._name;
    }
    function Foo_isFoo() {
        return true;
    }
    // --- export ----------------------------------------------
    if (global.process) { // node.js
        module.exports = Foo;
    }
    global.Foo = Foo;

    })(this.self || global);

1. Foo.repository = ... を追加します。

   Foo.repository = "https://github.com/{{user-name}}/Foo.js"; を追加します。
   {{user-name}} の部分は、GitHubのユーザ名に差し替えてください。

       Foo.name = "Foo";
   +   Foo.repository = "https://github.com/{{user-name}}/Foo.js";
       Foo.prototype.name  = Foo_name;  // Foo#name():String
       Foo.prototype.isFoo = Foo_isFoo; // Foo#isFoo():Boolean

2. wiki ページ( https://github.com/{{user-name}}/Foo.js/wiki/Foo )を作成します。

3. wiki/Foo ページに API の説明を追加します。
   Foo, Foo.prototype.name, Foo.prototype.isFoo に説明を追加します。
   ページ内リンクに対応するために、<a name="Foo"> も埋め込みます。

   <a name="Foo">
   # Foo
   new Foo(name:String) で Foo クラスのインスタンスを生成します ...
   
   <a name="Foo.prototype.name">
   ## Foo.prototype.name
   Foo.prototype.name():String は、Foo の名前を返します ...
   
   <a name="Foo.prototype.isFoo">
   ## Foo.prototype.isFoo
   Foo.prototype.isFoo():Boolean は、常に true を返します ...

4. function ... 以降に属性を追加します。
   Foo, Foo_name, Foo_isFoo に 属性(@help, @arg, @ret, @desc)を追加していきます。

   -   function Foo(name) {
   +   function Foo(name) { // @arg String: human name.
   +                        // @help: Foo
           this._name = name;
       }
   
       Foo.name = "Foo";
       Foo.repository = "https://github.com/{{user-name}}/Foo.js";
       Foo.prototype.name  = Foo_name;  // Foo#name():String
       Foo.prototype.isFoo = Foo_isFoo; // Foo#isFoo():Boolean
       // --- implement -------------------------------------------
   -   function Foo_name() {
   +   function Foo_name() { // @ret String: human name.
   +                         // @help: Foo#name
           return this._name;
       }
   
   -   function Foo_isFoo() {
   +   function Foo_isFoo() { // @ret Boolean: true is human
   +                          // @help: Foo#isFoo
           return true;
       }

5. package.json に uupaa.help.js を追加し、
   npm install で Help.js がインストールされるように、devDependencies に記述します。

       {
   +     "devDependencies": {
   +       "uupaa.help.js": ">= 0.8.0"
   +     }
       }

最終的な Foo.js はこのようなります。

    // Foo.js

    (function(global) {

    // --- define ----------------------------------------------
    // --- variable --------------------------------------------
    // --- interface -------------------------------------------
    function Foo(name) { // @arg String: human name.
                         // @help: Foo
        this._name = name;
    }

    Foo.name = "Foo";
    Foo.repository = "https://github.com/{{user-name}}/Foo.js";
    Foo.prototype.name  = Foo_name;  // Foo#name():String
    Foo.prototype.isFoo = Foo_isFoo; // Foo#isFoo():Boolean
    // --- implement -------------------------------------------
    function Foo_name() { // @ret String: human name.
                          // @help: Foo#name
        return this._name;
    }
    function Foo_isFoo() { // @ret Boolean: true is human
                           // @help: Foo#isFoo
        return true;
    }
    // --- export ----------------------------------------------
    if (global.process) { // node.js
        module.exports = Foo;
    }
    global.Foo = Foo;

    })(this.self || global);

Function式 と Function文

Help.js のサポートをうけるには、 function を、
function式(var fn = function() { ... }) ではなく、
function文(function fn() { ... }) の形で記述してください。

# 属性

関数を説明するために利用されている属性の一覧です。
Help.js は @help 属性をパースしますが、それ以外の属性は人が参照するための情報です。

名前	属性	内容	例
@help	ヘルプ	リンクを生成するための情報	@help: クラス名 @help: クラス名.prototype.メソッド名 @help: クラス名.静的メソッド名 @help: クラス名#メソッド名 省略記法
@arg または @param	引数	引数の型,デフォルト値,説明	@arg String: @arg NumberArray/Number(= 0): @arg Any(= undefined): @arg Object:
@var_args	可変長引数	引数の型,説明	@var_args: Any
@ret または @return	戻り値	戻り値の型,説明	@ret String: @ret this:
@desc または @description	概要	関数の概要	@desc: Convert String to Base64String.
@throw または @throws	例外	例外発生時のエラー型とエラーメッセージ	@throw: Error("invalid args")
@deprecated	廃止予定	将来的に廃止する場合に設定しておきます	@deprecated:

使用例

以下は、引数が複数あり、第二引数がデフォルト値をもっており、戻り値がある関数の定義例です。

• 第一引数は、Object 型または String 型を受け付けます。あらゆる型を受け付ける場合は Any にします。
• 第二引数は、Boolean 型を受け付けます。指定されなかった場合の値は false です。
• 戻り値は this なので、メソッドチェインが可能です。

(function(global) {

// --- define ----------------------------------------------
// --- variable --------------------------------------------
// --- interface -------------------------------------------
function Foo() { }

Foo.prototype.method = Foo_method; // Foo#method(arg1:Object/String, arg2:Boolean = false):this

// --- implement -------------------------------------------
function Foo_method(arg1,   // @arg Object/String: arg1 description
                    arg2) { // @arg Boolean(= false): arg2 description
                            // @ret this: return value
                            // @desc: Foo method description
                            // @help: Foo#method
    arg2 = arg2 || false;
    return this;
}
// --- export ----------------------------------------------
if (global.process) { // node.js
    module.exports = Foo;
}
global.Foo = Foo;

})(this.self || global);

以下は実際の使用例です。

• UTF8.js
• Task.js
• Postal.js
• Device.js
• Base64.js
• WordArray.js

# 省略記法

Foo.prototype.isFoo とタイプするのは少々手間なので、# を使って Foo#isFoo とできると便利です。

# による省略記法は、以下の場所で利用できます。

利用可能な場所
@help:	@help: Foo#isFoo
Help("...")	Help("Foo#isFoo")