Help.js

Online Reference

@uupaa - 2014-04-01

Help.js は


ブラウザと連携して動作する
まったく新しい
オンラインリファレンス機能
提供します

Help.js には

2つの目的があります


  1. ソースコードとドキュメントを分離します

    • ドキュメントが死蔵されず
      更新/拡充されるサイクルを目指します
  2. DevTools コンソールで機能する
    Help コマンドを提供します

ソースコードと
ドキュメントの分離は

モジュールの作者が
ドキュメントを
いつでもどこからでも
書きやすくし、


モジュールのユーザが
ドキュメントを
いつでもどこからでも
読めるようにするためのものです

ドキュメントを分離するために

( 1 ). リファレンスは Web に置きます


GitHub にリポジトリと
wiki ページを作成します


社外に置けるものは
社外に置きます

( 2 ). ソースコードに
キーワードを埋め込みます

  • リポジトリのURLと @help 属性 をコードに埋め込みます
+   Class.repository = "https://github.com/.../Class";

    // --- interface -------------------------------------------
-   function Class(value) {
+   function Class(value) { // @help: Class
    }

    // --- implement -------------------------------------------
-   function Class_method() {
+   function Class_method() { // @help: Foo#value
    }

( 3 ). ブラウザからリファレンスを
引けるようにしました


Help コマンドを使うことで
リファレンスページに素早くたどり着けます

Help コマンドは

関数の内容をダンプします


Foo.help で、
Fooクラスのコンストラクタをダンプします

> Foo.help

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

引数・型・戻り値などの情報を
クイックに確認できます

リンクを提示します


Foo.js のリファレンスページ
リポジトリの URL を提示します。

Web 全体から検索するための
Google 検索用の URL も提示します

> Foo.help

  Reference:
      https://github.com/uupaa/Foo.js/wiki/Foo#wiki-foo
  Repository:
      https://github.com/uupaa/Foo.js/
  Google.search( Foo ):
      http://www.google.com/search?lr=lang_ja&ie=UTF-8&oe=UTF-8&q=Foo

ネイティブ API を調べられます


Array.prototype.every.help とすると
Array#every を解説した MDN のリンク
Google 検索用の URL を提示します

> Array.prototype.every.help

  function every() { [native code] }

  MDN.search( Array.prototype.every ):
      http://www.google.com/search?q=MDN%20Array.prototype.every
  Google.search( Array.prototype.every ):
      http://www.google.com/search?q=Array.prototype.every

コンテキスト依存の検索ができます

Help("キーワード")
global や window オブジェクト以下から
キーワードと一致する関数や
プロパティを検索し
リンクを提示します。

キーワードが見つからない場合は
Google 検索用の URL を提示します

> Help("Array.isHoge")

Google.search( Array.isHoge ):
    http://www.google.com/search?lr=lang_ja&ie=UTF-8&oe=UTF-8&q=Array.isHoge

さらに詳しく知りたい方は…


Help.js のドキュメントをご覧ください


Help.js は WebModule で書かれています


こちらのドキュメントも
合わせて参照してください

このスライドにも
Help.js が組み込まれています


Command + Option + I や、
コンテキストメニューの 要素の検証 から DevTools を開き、
以下のコマンドを試してみてください

> Array.prototype.reduce.help

> Object.freeze.help

> Help("Task.flatten")

> Help.help