如何輕松創建 Github 友好的 markdown 以記錄 JavaScript 功能？

Question

我希望能夠在 JavaScript 源代碼中的任何地方使用這樣的 JSDoc 注釋（甚至嵌套在幾個函數層中，在一個模塊中，甚至是匿名函數中）：

/**
 *  Used to do some important thing that needs doing that works like xyz.
 *  @param {String} whatever - some string that has some purpose
 *  @param {Function} callback - a function that needs to be run
 *  @returns {Boolean} whether or not something happened
 */
 function something(whatever, callback) {
     ...

並有一些簡單的方法來生成漂亮的 markdown：

##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.

*Parameters*
  `whatever {String}` some string that has some purpose
  `callback {Function}` a function that needs to be run

*Returns*
   `{Boolean}` whether or not something happened

其中“root”是可以訪問 function 的命名空間。 或者，如果它是匿名的 function 或私有的 function（出於某種原因應該在公共 doco 中，這甚至有意義嗎？？），請使用其他一些約定來表示它。 可能是

##_private_function_ `something(whatever,callback)`

  and

##_anonymous_function_`(whatever,callback)`

它不必完全是那種格式，只要在 Github 上看起來不錯並且有意義即可。 理想的工具應該足夠智能，能夠使用Mustache.js之類的代碼並生成良好的 output。如果它可以處理大量源文件並生成一個文檔 output 或一組鏈接的文檔，則效果會更好，具體取決於配置。

最好是以一種可以完全輕松地包含在 git 存儲庫中的方式完成，這樣人們就不需要設置高度特定的工具鏈來更新 doco。 或者至少需要一個最小的工具鏈。

哦，還有一匹小馬。

---

現有選項

JSDoc ，加上某種 HTML -> markdown 轉換

JSDoc 非常好。 但我似乎無法讓它與模塊一起工作。 或者更確切地說，這比恕我直言應該更麻煩。 我不需要添加額外的標簽來命名 function。我已經嘗試了 @export 和 @name，但仍然無法按照我想要的方式將其顯示在最終文檔中。 如果有人可以指向一個 JSDoc 注釋源，其中包含模塊並且做得很好，那可能會有所幫助。 更新： JSDoc v3 實際上似乎比 v2 更適合模塊，所以這可能更合適。

即使我可以像我想要的那樣獲得 JSDoc output，我也需要從 HTML 轉換為 markdown。我似乎找不到一個好的工具，是否存在？

文檔下載

我玩過 Docdown 但事實上它是 PHP 對我來說有點不可能......

YUIDoc , 加上轉換

我實際上還沒有玩過 YUIDoc，但它看起來不錯。 盡管如此，我還是需要一個轉換器。 它是否輕松處理模塊並避免必須顯式提供 function 名稱和導出名稱？

Dox ，加上 markdown 模板

Dox 生成 JSON，因為它是 output，因此您需要將其與一些好的 markdown 模板結合，並包括一個模板引擎來生成文檔。 有沒有人以有用的方式將一組這樣的模板放在一起？

jGrouse ，加上轉換

使用 ANT 運行。接下來...

腳本文檔...

這甚至還存在嗎？ 似乎是 Aptana studio 的一部分，所以這將是一個失敗者...... Aptana 似乎沒有任何關於它的信息。 但是 ScriptDoc.org 有一些關於 crack 的有趣信息，如果有幫助的話......

文檔

Pdoc 基於 Ruby，但該工具鏈並不少見，因此這不是一個大問題。 您可以提供自己的模板，這樣也許已經有一些不錯的 markdown 模板了。 我沒玩過它...它值得嗎？ 那里有好的 markdown 模板嗎？

還有別的嗎？

外面還有什么？

自己做！

在與 JSDoc 搞了幾個小時試圖讓它按照我想要的方式工作之后，我放棄了並在 Java 中為CharFunk 編寫了我自己的快速而骯臟的解決方案，這是一個我一直在研究的 unicode JavaScript 庫。 雖然它還沒有接近通用目的，但它足以滿足我的需要。

---

所以.....

這是一個未滿足的需求還是只是我？

Answer 1

我用jsdoc-to-markdown ..

寫文檔代碼：

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

得到降價文檔：

$ jsdoc2md example/function.js

#protection(cloak, dagger)
a quite wonderful function

**Params**

- cloak `object` - privacy gown
- dagger `object` - security

**Returns**: `survival`

這些項目有jsdoc2md呈現的自述文件：

• 手剎-JS
• 陣列的工具
• 命令行-ARGS

Answer 2

你試過jsdox嗎？

它是一個node.js jsdoc到markdown生成器。

Answer 3

markdox可以從javascript代碼生成markdown文檔。

Answer 4

jsDox。 https://github.com/sutoiku/jsdox使用UglifyJS完整解析

莫克斯。 https://github.com/tjchaplin/mox幾個可立即運行的示例/模板。

兩者都處理JSDoc / Dox格式。 兩者都有積極的發展。 對我來說，Mox因為示例套件而獲勝。

Answer 5

好。 經過我自己的一些考慮，我會選擇DOX + Underscore / Whatever JS模板引擎。

應該很簡單。 你可能甚至可能會遇到Grunt或類似的東西，並讓它在監視任務下運行。

據我所知，Dox相對輕巧，並且有一個npm包（IIRC）。

更新：我想，經過一些經驗，我想改變我對YUIDoc的回答。

Answer 6

嘗試使用動詞 。 在最簡單的用例中，Verb將使用package.json中的數據從模板構建自述文件。

但是，如果您需要生成多頁TOC或創建自定義幫助程序等，動詞也具有高級功能。

關於API文檔，請參閱此示例使用index.js代碼注釋生成的自述文件。 點擊標題，這些也是自動生成的。 使用此內置幫助程序從指定的任何文件路徑生成API文檔。 您還可以使用glob模式從多個文件中提取文檔。

Verb將在沒有任何配置的情況下構建.verb.md 。 但是如果你需要更多，你可以使用verbfile.js

Answer 7

我需要從JSDoc創建一個API文檔，它應該易於使用，並且還支持現代前端堆棧。 一些提到的庫存在JS代碼轉換為babeljs的問題，因此您必須暫時使用注釋來轉換代碼以生成降價文檔。

對於這樣的用例，我發現http://documentation.js.org/非常有用，因為它們集成了對BabelJs配置的支持，因此它負責從JSDocs生成markdown（JSON，HTML）。