jwl*_*jwl 61 javascript markdown github jsdoc
我希望能够在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) {
...
并有一些简单的方法来产生好的降价:
##`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"是可以访问该函数的命名空间.或者,如果它是一个匿名函数或一个私有函数(由于某种原因应该在公共doco中,这甚至是有道理的吗??),使用一些其他约定来表示.也许
##_private_function_ `something(whatever,callback)`
and
##_anonymous_function_`(whatever,callback)`
它不一定是那种格式,只是在Github看起来很好并且有意义的东西.理想的工具足够聪明,能够像Mustache.js一样获取代码并产生良好的输出.如果它可以处理大量源文件并生成一个文档作为输出,或者根据配置生成一组链接文档,那将是额外的好处.
最好是以一种可以完全轻松地包含在git仓库中的方式完成,这样人们就不需要设置一个高度特定的工具链来更新doco.或者至少需要一个最小的工具链.
哦,还有一匹小马.
JSDoc非常好.但我似乎无法使其与模块配合良好.或者更确切地说,它应该是恕我直言,这是一个更大的麻烦.我不需要添加额外的标签来命名该功能.我已经尝试了@export和@name,但仍然无法让它以我想要的方式显示在最终文档中.如果某人可以指向一个JSDoc注释源,其中包含模块并且运行良好,那可能会有所帮助. 更新: JSDoc v3实际上看起来比使用v2更好,所以这可能更合适.
即使我能像我想的那样得到JSDoc输出,我也需要从HTML转换为markdown.我似乎无法找到一个好的工具,是否存在？
我在Docdown上玩了一下,但事实上它对我来说是一种不起作用的...
我实际上没有玩过YUIDoc,但看起来还不错.不过,我需要一个转换器.它是否容易处理模块并避免必须明确提供函数名称和导出名称？
Dox生成JSON作为它的输出,因此你需要将它与一些好的markdown模板结合,并且还包括一个模板引擎来生成文档.有没有人以有用的方式组合一组这样的模板？
用ANT运行.下一个...
这甚至还存在吗？似乎是Aptana工作室的一部分,所以这将是一个不起作用... Aptana似乎没有任何信息.但ScriptDoc.org有一些关于破解的有趣信息,如果这有用的话......
Pdoc是基于Ruby的,但工具链并不罕见,所以这不是一个大问题.你可以提供自己的模板,也许已经有一些好的降价.我没有玩过它......值得吗？那里有好的降价模板吗？
还有什么呢？
瞎搞与JSDoc试图让这工作,我怎么想了几个小时后,我放弃了,写我自己的快速和肮脏的解决方案在Java中的CharFunk,一个unicode JavaScript库,我一直在工作.它适用于我需要的东西,虽然它不接近通用目的.
这是一个未满足的需求还是仅仅是我？
Llo*_*oyd 19
我用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:
好的。经过一番深思熟虑后，我会选择 DOX + Underscore/Whatever JS 模板引擎而不是 Node。
应该很简单。您甚至可以插入 Grunt 或类似的程序，并让它在监视任务下运行。
据我所知，Dox 相对轻量级，并且有一个 npm 包（IIRC）。
更新：我想，经过一些经验，我想改变我对 YUIDoc 的答案。
| 归档时间： |
|
| 查看次数： |
16280 次 |
| 最近记录： |