ITエンジニア/デザイナ向けにオープンソースを毎日紹介

jQueryの普及などに伴って外部ライブラリを導入することが増えてきました。そのような時にそのメソッドや使い方を調べようと思うとライブラリのドキュメントをあたらないといけません。これはとても面倒です。

そこでライブラリ自身にヘルプ機能を持たせてしまってはどうかというライブラリがHelp.jsになります。まずはその使い方を見てみましょう。

サンプルとしてFooというオブジェクトがあるとします。コードはこんな感じです。

// Foo.js

(function(global) {

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

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

})(this.self || global);

後はHelp.jsを読み込んだ後、DevToolsのコンソールでHelpコマンドが使えるようになります。

Help('Foo')で呼び出される内容です。
Help('Foo')で呼び出される内容です。

オブジェクトの説明と、調べるためのURLが出ます。

さらにFoo.helpというメソッドも追加されます。結果は上記と同じです。
さらにFoo.helpというメソッドも追加されます。結果は上記と同じです。

メソッドを調べることもできます。
メソッドを調べることもできます。

コードの中にドキュメントを埋め込むというのはJavaDoc時代から変わっていませんが、それをWebブラウザ上のDevToolsで確認できるようにするというのは面白いアイディアです。こうすれば使えるメソッドの使い方を載せたり、細かなドキュメンテーションが可能になりそうです。

Help.jsはnode/JavaScript製のオープンソース・ソフトウェア(MIT License)です。

uupaa/Help.js

 

MOONGIFTの関連記事

コメント

  • DevRel
  • Com2