雅虎用戶界面博客（YUIBlog）

卡羅Zottmann的達納主題為YUI文檔

2010年10月1號在上午07:46由Carlo Zottmann |在開發 | 2評論

我喜歡用YUI文檔為我所有的JavaScript文件的需要。 我發現它很適合記錄普通香草JS或jQuery代碼-它不僅為YUI的項目。

起初我是持懷疑態度，因為我傾向於寫更多的jQuery比YUI代碼。 這是一個驚喜地發現，YUI文檔輕鬆地集成到我的工作流程，並能產生有用的文檔，我的非YUI項目。 當然，它有一定的期望，針對項目的文件結構等，但這些都沒有對我的期望是攪局者。 另一方面，它是一個燈光系統，我可​​以得到它，並運行在任何時間。

擁有一個工具解析我的源代碼，並自動地生成高質量的文檔對我來說是偉大的 - 不僅對迅速查找函數調用等以後，對我來說，增加值在兩個方面：

首先，我不是我的代碼文件的方式為自己著想 - 我可能將不得不重新訪問它在數個月，我應該能夠把它撿起來迅速。 由於沒有文件意味著在未來的某些混亂，這不是一個印象，我想給我的客戶。

其次，代碼文檔可能會有點的一個抽象的概念，為客戶：我可以告訴她它的存在，但只有這樣我可以“證明”我的要求是由射擊我的編輯和點我的手指在註釋塊在我代碼。 這真的很令人印象深刻的不看 - 在最壞的情況，他們看起來像一個遺憾藉口“正當”的文件。

然而，發射了我的瀏覽器並顯示同樣的意見進行分析和處理 YUI文檔 - 清潔，波光粼粼，連貫的 - 現在的專業代碼弄亂右有，人。

（如果你只是想“代碼記錄在維基一樣好，少麻煩”，請接受我傷心高爾夫鼓掌-因為它不是。）

不幸的是，我不是一個球迷的基本YUI文檔的皮膚。 當我交出紮實記錄片的代碼給我的客戶，我希望他們看到的紮實記錄代碼，對我來說，YUI文檔的默認主題沒有足夠的光芒。

環顧更換主題我找不到任何。 因此，在幾個星期前，我決定寫我自己的- 達納 。 下面是一個例子截圖：

正如你可以在上面看到，我已經產生了著名的YUI API文檔為例。 這裡的原YUI文檔 -這裡是非常相同的文檔體育新達納主題 。

我覺得後者更順眼 - 我希望你同意！ 按了一下周圍，檢查一些類 documentations進行更深入的比較，玩的過濾器，豪華的感覺還便宜的塑料底。

到目前為止，我已經得到了大量的積極反饋。 我的客戶體會到更清潔的樣子，我覺得更好地了解和更專業的演示的工作我把我的項目，一直到生成的標記。

它是如何建

我開始寫達納由扔掉每一點的HTML裡面默認YUI文檔模板，開始了從無到有，從我自己的標記分層之上的核心區塊的YUI文檔獵豹代碼。 （獵豹是Python模板引擎使用YUI文檔的#塊，你會發現在模板中包含Python代碼執行的獵豹。）

說實話，搞清楚發生了什麼事情在模板是不是一個真正的公園散步 - YUI文檔的模板不註明，並獲得導向作為一個新人到系統花了一些時間。 當我感覺我理解的邏輯結構和獵豹，我去內臟，其餘的標記，取代它與一些非常簡單的結構，以及建立在之上的。 過了好一會兒。

如果你想編寫自己的主題，我建議你要么使用德納main.tmpl為出發點，或看的格式正確的原始main.tmpl 。 許多 Bothans死給你帶來這個模板。

我不是一個設計師，我一直試圖保持外觀簡單明了無需增加很多花里胡哨的。

內置的超值服務

我已經採取了自由實施一個（恕我直言）更好的顯示對象類型的參數：如果有多個參數傳遞的屬性對單個對象，只是對象將顯示為一個參數表中的第一列。

作為一個例子，假設你記錄的方法預期的對象類型的參數包含三個屬性：

 * @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文檔和運​​行在這一點上。 只要下載達納從GitHub ，解開它，並告訴yuidoc.py使用它通過-t/--template選項。

閉幕詞

達娜仍然是一個工作的進展情況;也有一些小問題離開，例如一些HTML code塊的出來太寬。 這些都不是我處理斷路器 ，但您的里程可能會有所不同。

對於讀者誰和我一樣，這個想法得到頭暈的降價支持YUI文檔像我這樣做（提示，提示），檢查了邁克西方的YUI文檔叉它增加了準確的。 雖然我們等待一個新的原始YUI文檔的發布，我的意思。*咳嗽;）*

你會發現達納GitHub上 。 如果你願意，你可以下載最新的穩定版本為ZIP / tgz文件 ，也。 如果遇到任何錯誤，請創建票證 。

達納是雙授權下MIT＆GNU GPL V2。 它已經在Safari中測試 5（OSX），FF3.6（OSX），IE8（的WinXP）。

查找談話： bloglines | technorati

共享和擴展： 書籤與del.icio.us | Digg它！ | 書籤交易！