如何轻松地为文档化的 JavaScript 函数创建 Github 友好的 Markdown？
声明：本页面是StackOverFlow热门问题的中英对照翻译，遵循CC BY-SA 4.0协议，如果您需要使用它，必须同样遵循CC BY-SA许可，注明原文地址和作者信息，同时你必须将它归于原作者（不是我）：StackOverFlow
原文地址: http://stackoverflow.com/questions/15694267/
Warning: these are provided under cc-by-sa 4.0 license. You are free to use/share it, But you must attribute it to the original authors (not me):
StackOverFlow
How to easily create Github friendly markdown for documented JavaScript functions?
提问by jwl
I want to be able to take JSDoc comments like this anywherein JavaScript source (even nested down several layers of functions, in a module or even anonymous functions):
我希望能够在 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) {
...
and have some easy way to produce nice 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
Where "root" is the namespace at which that function is reachable. Or if it's an anonymous function or a private function (that for some reason should be in public doco, does that even make sense??), use some other convention to denote that. Maybe
其中“root”是可以访问该函数的命名空间。或者，如果它是匿名函数或私有函数（出于某种原因应该在公共文档中，这甚至有意义吗？？），请使用其他一些约定来表示。或许
##_private_function_ `something(whatever,callback)`
and
##_anonymous_function_`(whatever,callback)`
It doesn't have to be exactly that format, just something that looks good on Github and makes sense. The ideal tool would be smart enough to be able to take code like Mustache.jsand produce good output. And extra good would be if it can handle lots of source files and produce one document as output, or a linked set of documents depending on configuration.
它不必完全是那种格式，只要在 Github 上看起来不错并且有意义。理想的工具应该足够智能，能够使用Mustache.js 之类的代码并产生良好的输出。如果它可以处理大量源文件并生成一个文档作为输出，或者根据配置生成一组链接的文档，那就更好了。
And it would be best if this was done in a way that can be fully and easily included in a git repo so that people don't need to set up a highly specific toolchain to update the doco. Or require a minimal toolchain at least.
最好是以一种可以完全轻松地包含在 git repo 中的方式来完成，这样人们就不需要设置高度特定的工具链来更新 doco。或者至少需要一个最小的工具链。
Oh, and a pony.
哦，还有一匹小马。
Existing options
现有选项
JSDoc, plus some kind of HTML -> markdown conversion
JSDoc，加上某种 HTML -> Markdown 转换
JSDoc is pretty good. But I can't seem to make it work well with modules. Or rather, it's a bigger hassle than it ought to be IMHO. I shouldn't need to add an extra tag to name the function. I've tried the @export and @name and still have trouble getting it to show up in the final doc the way I'd want. If someone can point to a JSDoc commented source that has modules in it and is done well, that might help. Update:JSDoc v3 actually seems much better with modules than v2 so this might be a better fit.
JSDoc 很不错。但我似乎无法让它与模块一起工作。或者更确切地说，这比恕我直言更麻烦。我不需要添加额外的标签来命名函数。我已经尝试了@export 和@name，但仍然无法按照我想要的方式将其显示在最终文档中。如果有人可以指出其中包含模块并且做得很好的 JSDoc 注释源，那可能会有所帮助。 更新：JSDoc v3 实际上看起来比 v2 更适合模块，所以这可能更合适。
Even if I could get JSDoc output like I want, I'd need to convert from HTML to markdown. I can't seem to find a good tool for that, does one exist?
即使我可以得到我想要的 JSDoc 输出，我也需要从 HTML 转换为 Markdown。我似乎找不到一个好的工具，有吗？
Docdown
下载
I played a bit with Docdown but the fact it's PHP is kind of a nonstarter for me...
我玩过 Docdown 但事实上它是 PHP 对我来说有点不可思议......
YUIDoc, plus conversion
YUIDoc，加上转换
I actually haven't played with YUIDoc but it looks ok. Still, I would need a converter. Does it deal with modules easily and avoid having to supply the function name and export name explicitly?
我实际上还没有玩过 YUIDoc，但看起来还不错。不过，我需要一个转换器。它是否轻松处理模块并避免必须明确提供函数名称和导出名称？
Dox, plus markdown templates
Dox，加上降价模板
Dox produces JSON as it's output, so then you'd need to marry that to some good markdown templates, and plus include a template engine to generate the documents. Has anyone put together a set of such templates in a useful fashion?
Dox 在输出时生成 JSON，因此您需要将其与一些好的 Markdown 模板结合起来，并包含一个模板引擎来生成文档。有没有人以有用的方式组合了一组这样的模板？
jGrouse, plus conversion
jGrouse，加上转换
Runs with ANT. Next...
与 ANT 一起运行。下一个...
ScriptDoc...
脚本文档...
Does this even exist anymore? Seems to be part of Aptana studio so that would be a nonstarter... Aptana doesn't seem to any info on it. But ScriptDoc.org has some interesting information on crack, if that's helpful...
这还存在吗？似乎是 Aptana 工作室的一部分，所以这将是一个不可能的事情...... Aptana 似乎没有任何关于它的信息。但是 ScriptDoc.org 有一些关于破解的有趣信息，如果有帮助的话......
Pdoc
博士
Pdoc is Ruby based but that toolchain is not uncommon so that's not a huge problem. You can provide your own templates so maybe there are already some good markdown ones. I haven't played with it... is it worthwhile? Are there good markdown templates out there?
Pdoc 是基于 Ruby 的，但该工具链并不少见，因此这不是一个大问题。您可以提供自己的模板，因此也许已经有一些不错的 Markdown 模板。我没玩过……值得吗？有没有好的降价模板？
Something else?
还有什么？
What else is out there?
外面还有什么？
Make your own!
自己做！
After messing around with JSDoc for a few hours trying to make it work how I wanted, I gave up and wrote my own quick and dirty solution in Javafor CharFunk, a unicode JavaScript library I've been working on. It works well enough for what I need though it's not close to general purpose yet.
在与 JSDoc 混了几个小时试图让它按照我想要的方式工作之后，我放弃了，并用 Java为CharFunk编写了我自己的快速而肮脏的解决方案，这是我一直在研究的一个 unicode JavaScript 库。尽管它还不是通用的，但它足以满足我的需要。
So.....
所以.....
Is this an unmet need or is it just me?
这是一个未满足的需求还是只是我？
采纳答案by Steven de Salas
回答by Lloyd
I use jsdoc-to-markdown..
我使用jsdoc-to-markdown..
write documented code:
编写文档代码：
/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}
get markdown docs:
获取降价文档：
$ jsdoc2md example/function.js
#protection(cloak, dagger)
a quite wonderful function
**Params**
- cloak `object` - privacy gown
- dagger `object` - security
**Returns**: `survival`
These projects have readme files rendered by jsdoc2md:
这些项目具有通过jsdoc2md以下方式呈现的自述文件：
回答by user2367031
回答by Chris Buck
jsDox. https://github.com/sutoiku/jsdoxFull parse using UglifyJS
jsDox。https://github.com/sutoiku/jsdox使用 UglifyJS 进行完整解析
Mox. https://github.com/tjchaplin/moxSeveral ready-to-run examples/templates.
莫克斯。https://github.com/tjchaplin/mox几个准备运行的示例/模板。
Both handle JSDoc/Dox formats. Both have active development. For me, Mox wins because of the example suite.
两者都处理 JSDoc/Dox 格式。两者都有积极的发展。对我来说，Mox 获胜是因为示例套件。
回答by ZenMaster
OK. After some deliberation with myself, I'd go with DOX + Underscore/Whatever JS templating engine over Node.
行。在与自己深思熟虑之后，我会在 Node.js 上使用 DOX + Underscore/Whatever JS 模板引擎。
Should be pretty simple. You can, possibly, even jam into Grunt or similar and have it ran under a watch task.
应该很简单。你甚至可以进入 Grunt 或类似的东西，让它在监视任务下运行。
Dox is, from what I can recall, is relatively lightweight and has an npm package (IIRC).
据我所知，Dox 是相对轻量级的，并且有一个 npm 包 (IIRC)。
UPDATE: I think, after some experience, that I'd like to change my answer to YUIDoc.
更新：我想，经过一些经验，我想改变我对 YUIDoc 的回答。
回答by jonschlinkert
Try using Verb. In the simplest use case Verb will build a readme from a template using data from package.json.
尝试使用动词。在最简单的用例中，Verb 将使用 package.json 中的数据从模板构建自述文件。
But verb also has advanced features if you need to generate multi-page TOCs, or create custom helpers, etc.
但是如果您需要生成多页 TOC 或创建自定义助手等，动词也具有高级功能。
Regarding API documentation, see this example readmegenerated using code comments from index.js. Click on the headings, those are auto-generated too. Use this built-in helperto generate API docs from whatever file path is specified. You can also use glob patterns to pull in docs from multiple files.
关于API文档，看到这个例子自述使用代码注释，从生成index.js。单击标题，这些也是自动生成的。使用此内置帮助程序从指定的任何文件路径生成 API 文档。您还可以使用 glob 模式从多个文件中提取文档。
Verb will build a .verb.mdwithout any config. But if you need more, you can use a verbfile.js
Verb 将构建一个.verb.md没有任何配置的。但是如果你需要更多，你可以使用一个verbfile.js
回答by Fer To
I had the need of creating a API documentation out of JSDoc which should be easy to use and also supports modern frontend stacks. Some of the mentioned libraries have issues with JS code transpiled into babeljs therefore you have to transpile your code with comments temporarily just to generate your markdown documentation.
我需要从 JSDoc 创建一个 API 文档，它应该易于使用并且还支持现代前端堆栈。一些提到的库在将 JS 代码转换为 babeljs 时存在问题，因此您必须临时使用注释来转换您的代码，以生成您的 Markdown 文档。
For such use case I found http://documentation.js.org/quite useful as they have integrated support for BabelJs configurations so it takes care of generating markdown (JSON, HTML) from your JSDocs.
对于这种用例，我发现http://documentation.js.org/非常有用，因为它们集成了对 BabelJs 配置的支持，因此它负责从您的 JSDoc 生成降价（JSON、HTML）。
