ヤフーユーザーインターフェイスブログ（YUIBlog）

YUI docに関するモンテカルロZottmannのダナのテーマ

私が使用したいYUI Docをすべて私のJavaScriptの文書のニーズに。 私はそれがプレーンバニラJSやjQueryのコードを記述するためにうまく動作することを発見した-それはのためだけではありませんYUIベースのプロジェクト。

私はもっと書く傾向にあるように私は、最初は懐疑的だったjQueryの YUIコードより。 それはYUI Docは簡単に私のワークフローに統合を見つけることにうれしい驚きだったし、私の非YUIプロジェクトのための有用な文​​書を作り出すことができる。 確かに、プロジェクトのファイル構造などに関するいくつかの期待を持っていますが、これらの期待のどれも私にとっては致命ありません。 その一方で、それは光システムであり、私はそれを取得し、時間がないで実行することができます。

ツールは、私のソースコードを解析し、自動的に私のために品質のドキュメントを構築することに最適です - だけでなく、迅速など、後で関数呼び出しを調べるために、私には、2つの方法で値を追加します。

まず、私は自分のために私のコードのいずれかの方法を文書化する - 私はおそらく数ヶ月でそれを再訪問する必要がありますするつもりだと私はすぐにそれを拾うことができるはずです。 資料を持っていない、私は私の顧客を与えたい印象はありません将来の一定の混乱を意味します。

第二に、コードのドキュメントでは、クライアントの抽象的な概念のビットかもしれない：私はそれがあるか、私は "証明"することができる唯一の​​方法は私の主張は私のエディタを焼成することによってである彼女に言うと私のコメントブロックで私の指を指すことができますコー​​ド。 これは本当に非常に印象的に見えない - 最悪の場合、彼らは "適切な"ドキュメンテーションのための残念言い訳のように見えます。

まだ私のブラウザを発射し、YUIドクによって解析され、処理が非常に同じコメントを示す - ことは、人々、右がmonkeyingプロフェッショナルコードです。今すぐ予約 - きれいで、輝く、首尾一貫しています。

（あなただけの"ウィキに記載されたコードとして良いと手間の小さい"と思ったら、私の悲しいゴルフ拍手を受け入れてください-それはではないので。）

残念ながら、私はベースYUIドク皮膚のファンではない。 私は私のクライアントへのコードのしっかりと文書化作品以上の手は、私は彼らがしっかりと文書化されたコードを見たいときに、私には、YUI Docのデフォルトのテーマは明るく輝き、十分ではありません。

私はすべてを見つけることができませんでした交換のテーマを探しまわって。 数週間前、私は自分自身を書くことにしたので- ダナ 。 ここで例のスクリーンショットは次のとおりです。

あなたは上記を参照できるように、私は、例としてよく知られているYUIのAPIドキュメントを生成した。 ここにあるオリジナルのYUIのドキュメントでは、 -そしてここに新しいスポーツの非常に同じドキュメントであるダナのテーマは 。

私が目に後者より多くの楽しいを見つける - 私はあなたが同意するね！ 少し周りをクリックして、比較の深さの詳細については、クラスのドキュメントのいくつかをチェックして、フィルタで遊ぶ、豪華な、まだ安価なプラスチック製の下を感じています。

これまでのところ、私は肯定的なフィードバックをたくさんもらいました。 私のクライアントは、掃除機の外観を感謝し、私は生成されたマークアップに至るまで、私のプロジェクトに入れての作業よりプロフェッショナルなプレゼンテーションについてよりよく感じる。

それが建設された方法

私は、デフォルトYUIドキュメントテンプレート内のHTMLのすべてのビットを捨てYUI Docのコアブロックの上に傷や階層化自分のマークアップから上に起動することによって、ダナを書き始めたチーターコード。 （チーターはYUIドキュメントで使用されるPythonのテンプレートエンジンです。 #は、テンプレートで見つけるブロックがチーターによって実行されるPythonコードが含まれています。）

正直に言うと、テンプレートで何が起こっているかを考え出すのは本当に公園の散歩ではなかった - YUI Docのテンプレートには、注釈が付けられていないと、システムへの新来者は、いくつかの時間がかかったように配向なって。 私は構造とチーターのロジックを理解した感じがしたとき、私はいくつかの本当にシンプルな構文に置き換えて、マークアップの残りの部分を全焼し、その上に構築された。 それは時間がかかりました。

あなたが独自のテーマを書くことを考えると、私はダナの使用して、いずれかのお勧めmain.tmpl出発点として、または見て適切にフォーマットされたオリジナルmain.tmpl 。 多くのBothansはあなたにこのテンプレートをもたらすために死亡した。

私はデザイナーでないです、私は多くの添えものを追加することなく、外観はシンプルかつ明確に維持しようとしました。

内蔵のグッズ

私は、オブジェクト型のパラメータ（IMHO）優れたディスプレイを実装するための自​​由を撮影した：いくつかのパラメータは、単一のオブジェクトのプロパティとしてで渡された場合のみ、そのオブジェクトは、テーブル '最初の列内のパラメータとして表示されます。

例として、例えば、あなたは、3つのプロパティを含むオブジェクト型のパラメータを期待するメソッドを文書化していると言う。

 * @param obj.param1 {String} A string! * @param obj.param2 {Number} A number! * @param obj.param3 {Boolean} A boolean, surprisingly! 

ここでは、このメソッドが生成されたドキュメントに表示される方法は次のとおりです。

デフォルトのテーマ： method( obj.param1, obj.param2, obj.param3 )
ダナのテーマ： method( obj )

実際の例については、用ドキュメントを参照してくださいYAHOO.widget.DataTableのイベント 。

私はこの治療法は、出力がより簡潔になることがわかります。

必要条件

ダナは、次のいずれかが必要です後YUIドキュメントのビルドを 、例えば、ビルド50は正常に動作-しかし、 それはYUIドク1.0.0b1では動作しません。

インストール/使用方法

私はあなたがYUI Docを起きたと仮定し、この時点で実行している。 単にダウンロードしてgithubからダナを 、解凍して、言うyuidoc.pyを介してそれを使用する-t/--templateオプションを選択します。

閉会の辞

ダナはまだ進行中の作業です。いくつかのHTMLの例は、左側のいくつかのマイナーな問題があるcode幅が広すぎる出てくるブロックが。 これらは私のためにブレーカーを対処されていませんが、あなたのマイレージは変わる場合があります。

私のように、私はのようにYUI DocのMarkdownをサポート（ヒント、ヒント）のアイデアで目まいがする、読者のために、チェックアウトマイクWestのYUIのDocフォーク正確に追加します。 我々は新しいオリジナルYUIドクのリリースを待つ間、私は意味します。*咳;) *

あなたはよGitHub上でダナを見つける 。 あなたがその気であれば、あなたはダウンロードすることができますZIP / TGZフ ​​ァイルとして最新の安定版リリースをも。 何かエラーが発生した場合は、してくださいチケットを作成 。

ダナは、MIT＆GNU GPL v2のデュアルライセンスの下です。 それは、Safari 5（OSX）、FF3.6（OSX）、IE8（WinXPの）でテストされている。

会話を検索： Bloglinesの | テクノラティ

共有および拡張： del.icio.usでブックマーク | Diggそれ！ | reddit！