AddHelp

自分の JavaScript コードに Help.js を組み込む

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

before.js と after.js を例に説明します。

after.js に WebModule の機能を追加した完成形が見たい方は Foo.js を参照してください。

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

    // Foo.js

    (function(global) {

    // --- variable --------------------------------------------
    // --- define ----------------------------------------------
    // --- interface -------------------------------------------
    function Foo(value) {
        this._value = value;
    }
    Foo.prototype["value"]     = Foo_value;
    Foo.prototype["isNumber"]  = Foo_isNumber;
    Foo.prototype["isInteger"] = Foo_isInteger;
    // --- implement -------------------------------------------
    function Foo_value() {
        return this._value;
    }
    function Foo_isNumber() {
        return typeof this._value === "number";
    }
    function Foo_isInteger() {
        return typeof this._value === "number" &&
               Math.ceil(this._value) === this._value;
    }
    // --- export ----------------------------------------------
    if ("process" in global) {
        module["exports"] = Foo;
    }
    global["Foo"]  = Foo;

    })((this || 0).self || global);

Foo.name = "Foo"; を追加します。

IE では Foo.name が undefined になってしまい、クラス名を簡単に取得できません。
Foo.name への代入は、クロスブラウザのためのコードです。
Foo.repository = ... を追加します。

Foo.repository = "https://github.com/GITHUB-USER-NAME/Foo.js"; を追加します。
GITHUB-USER-NAME の部分は、実際のユーザ名に読み替えて下さい。
```
    Foo.name = "Foo";
+   Foo.repository = "https://github.com/GITHUB-USER-NAME/Foo.js";
    Foo.prototype.name  = Foo_name;
    Foo.prototype.isFoo = Foo_isFoo;
```
wiki ページ( https://github.com/GITHUB-USER-NAME/Foo.js/wiki/Foo )を作成します。
wiki/Foo ページに API の説明を追加します。
Foo, Foo.prototype.value, Foo.prototype.isNumber, Foo.prototype.isInteger に説明を追加します。
ページ内リンクに対応するために、<a name="..."> も埋め込みます。

こちらを参考にしてください。

function ... 以降に属性を追加します。
Foo, Foo_value, Foo_isNumber, Foo_isInteger に @help 属性を追加していきます。

余裕がある場合は、他の属性(@arg, @ret, @desc)も追加します。

-   function Foo(value) {
+   function Foo(value) { // @arg Number/Integer: the value.
+                         // @help: Foo
        this._value = value;
    }

    Foo.name = "Foo";
    Foo.repository = "https://github.com/GITHUB-USER-NAME/Foo.js";
    Foo.prototype.value     = Foo_value;
    Foo.prototype.isNumber  = Foo_isNumber;
    Foo.prototype.isInteger = Foo_isInteger;

    // --- implement -------------------------------------------
-   function Foo_value() {
+   function Foo_value() { // @ret Number/Integer: get value.
+                          // @help: Foo#value
        return this._value;
    }

-   function Foo_isNumber() {
+   function Foo_isNumber() { // @ret Boolean: valie is Number
+                             // @help: Foo#isNumber
        return typeof this._value === "number";
    }

-   function Foo_isInteger() {
+   function Foo_isInteger() { // @ret Boolean: valie is Integer
+                              // @help: Foo#isInteger
        return typeof this._value === "number" &&
               Math.ceil(this._value) === this._value;
    }

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

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

    // Foo.js

    (function(global) {

    // --- variable --------------------------------------------
    // --- define ----------------------------------------------
    // --- interface -------------------------------------------
    function Foo(value) { // @arg Number: the value.
                          // @help: Foo
        this._value = value;
    }

    Foo.name = "Foo";
    Foo.repository = "https://github.com/GITHUB-USER-NAME/Foo.js";
    Foo.prototype.value     = Foo_value;
    Foo.prototype.isNumber  = Foo_isNumber;
    Foo.prototype.isInteger = Foo_isInteger;

    // --- implement -------------------------------------------
    function Foo_value() { // @ret Number: get value.
        return this._value;
    }

    function Foo_isNumber() { // @ret Boolean: valie is Number
        return typeof this._value === "number";
    }

    function Foo_isInteger() { // @ret Boolean: valie is Integer
        return typeof this._value === "number" &&
               Math.ceil(this._value) === this._value;
    }

    // --- export ----------------------------------------------
    if (process in global) { // node.js
        module["exports"] = Foo;
    }
    global["Foo"] = Foo;

    })((this || 0).self || global);

Function式と Function文

Help.js のサポートをうける関数は、function 式ではなく、function 文の形で記述してください。

// function式
var fn = function() {
};

// function 文
function fn() {
}

# 属性

関数の機能と役割を説明するために、以下の属性を使ってマークアップします。
Help.js は @help 属性をパースしますが、それ以外の属性は人が参照するための情報です。

名前	意味	内容	例
`@help`	ヘルプ	リンクを生成するための情報	`@help: クラス名` `@help: クラス名.prototype.メソッド名` `@help: クラス名.静的メソッド名` `@help: クラス名#メソッド名` 省略記法
`@arg` または `@param`	引数	引数の型,デフォルト値,説明。複数の型を受け取る場合は、スラッシュ(/), パイプ(\|)で区切って列挙します。あらゆる型を受け取る場合は Any を使います	`@arg String:` `@arg Object:` `@arg NumberArray/Number(= 0):` `@arg Any(= undefined):`
`@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:`
その他の属性		利用は自由です。意味は JavaDoc のそれに準じます

使用例

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

第一引数は、Object 型または String 型を受け付けます。
第二引数は、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);

Help.js の導入例も参考にしてください。

# 省略記法

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

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

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

TypeDecoration

URL に限定された String は URLString と表記したほうが情報量が増え、
Number だけを要素に持つ配列は NumberArray と表記したほうが情報量が増えます。

同様に URLString の配列は URLStringArray と表記したほうが、よりスマートに型の性質を捉える事ができます。

このように、型名の手前に、修飾子と要素の型を連結し ◯◯Array のように表記するやり方を TypeDecoration と呼んでいます。

型の性質	基本型	修飾表記
URL文字列	String	@arg URLString: "url"
絶対URLの文字列	String	@arg AbsoluteURLString: "http://..."
絶対URLの文字列の配列	String	@arg AbsoluteURLStringArray: ["http://...", ...]
数値の配列	Array	@arg NumberArray: [number, ...]
StringのKeyとNumberのValueをペアにした配列	Array	@arg StringKeyAndNumberValuePairArray: [`<key:String, value:Number>`, ...]

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

AddHelp

自分の JavaScript コードに Help.js を組み込む

Function式と Function文

使用例

TypeDecoration

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

AddHelp

自分の JavaScript コードに Help.js を組み込む

Function式 と Function文

使用例

TypeDecoration

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally

Function式と Function文