- html - 出于某种原因,IE8 对我的 Sass 文件中继承的 html5 CSS 不友好?
- JMeter 在响应断言中使用 span 标签的问题
- html - 在 :hover and :active? 上具有不同效果的 CSS 动画
- html - 相对于居中的 html 内容固定的 CSS 重复背景?
我一直看到以下格式的 JSDoc(和之前的 JavaDoc):
/**
* This is some JSDoc ...
* ... and some more
*/
function foo() {
但是,我的一位同事不希望使用首字母星号,即:
/**
This is some JSDoc ...
... and some more
*/
function foo() {
当我在 Eclipse 中尝试这样做时,它仍然将代码识别为 JSDoc(它的颜色不同于非 JSDoc 注释)。然而,当我查看 JSDoc 网站时,所有示例都包含星号……但是话又说回来,我也找不到任何说明它们是必需的(老实说,JSDoc 网站似乎有点糟糕)。
因此,考虑到我什至找不到 JSDoc 是什么/不是什么的正确规范,我想我会问 Stack Overflow。这里的任何人都可以指出我:
A) 某种规范引用(例如来自 JSDoc 站点的内容)说初始星号是/不是必需的
B) 没有初始星号的地方会出现问题的例子(例如,“除非你有初始星号,否则你不能使用很酷的 JSDoc 库 X”)
*编辑*
澄清一下,我们目前不使用 JSDoc 文档生成器。这个问题更多地来自于以行业标准方式格式化我们的注释的愿望,以及(在未来的某一天)能够使用依赖于 JSDoc 标准的工具(例如 JSDOc 文档生成器)的愿望。
基本上我真的不在乎我的同事如何格式化他的 JSDoc,我只是不希望非标准的做法在未来造成问题(如果我们 future 有这样的问题,我我希望能够向他解释,而不仅仅是说“我不喜欢你格式化 JSDoc 的方式”)。
最佳答案
没有所谓的“行业标准”jsdoc 格式。有 jsdoc 3它以某种方式工作,并且有jsdoc 2它以相似但不同的方式工作。有一个 jsdoc 1但我不知道有人仍然在生产中使用它。然后有一些工具尝试处理 jsdoc 的标记,或多或少地成功了。
行首的星号是可选的,这通常是正确的,但并非在所有情况下都是正确的。例如,如果将 jsdoc 3 与 Markdown plugin 一起使用,然后:
Also, be sure to use leading asterisks in your doc comments! If you omit the leading asterisks, JSDoc's code parser may remove other asterisks that are used for Markdown formatting.
所以 jsdoc 的各种版本都不需要前导星号,但有一些用例场景绝对需要前导星号。 (我在 jsdoc 3 的文档中没有找到直接说明星号 是可选的位置。但是,上面的引用暗示它们是。)
但有一件事,在此处提出的问题中,两个代码片段都以 /*
开头。 jsdoc 的所有版本,从 jsdoc 1 到 jsdoc 3,都需要将要作为 jsdoc 注释处理的注释标记为 with two or more asterisks。像这样开始 /**
.
关于jsdoc - "valid"JSDoc 是否需要星号?,我们在Stack Overflow上找到一个类似的问题: https://stackoverflow.com/questions/22465878/
短版: 如果我想从头开始开发一个全新的 jsDoc 模板,我需要阅读哪些内容才能了解 jsDoc 的功能、我的模板必须提供什么接口(interface)以及我可以使用哪些数据? 加长版: 我已经使用
给定一个将回调函数作为参数的 Javascript 函数: var myFunction = function(onSuccess, onFailure) {...} 我如何记录 onSuccess的
我一直看到以下格式的 JSDoc(和之前的 JavaDoc): /** * This is some JSDoc ... * ... and some more */ function
假设我有一个接受一个参数的函数: /** * @summary Some function. * * @since 1.0.0 * * etc. */ function func( a )
所有官方 JSDoc 示例都有简单的文档字符串,如下所示: /** * @param {string} author - The author of the book. */ 问题是,在现实生活中
jsDoc 似乎支持大部分 MD 语法,但是当涉及到突出显示单个保留字或文本时,我找不到可用的标签。 在 MD 语法中,我可以使用 `word`,它会设置灰色背景和不同的字体,这样您就可以清楚地看到它
我正在提供带有 JSDoc 注释的代码示例,其中也包含 JSDoc 注释,如何在不破坏外部注释的情况下转义嵌套的 JSDoc 注释? 我使用的是版本 3.3.0-beta3 例子: /** *
我正在使用 documentation package ,但无法弄清楚如何将它记录为类属性(不是通过 getter 和 setter 定义的)。 下面只为 SomeClass 生成类文档,但省略了 s
请向我解释描述此模块的最佳方式: /** * Common util methods * @module Utils */ var Utils = (/** @lends module:Util
我一直很难让 @borrows 标记在 JSDoc 中工作。我一直在尝试从一个函数中获取文档,并将其作为第二个函数的文档。但我似乎连一个简单的例子都做不到! /** * This is the de
我想设置一个 Grunt 任务来运行 JSDoc。我正在使用 grunt-jsdoc JSDoc npm 页面推荐的。它工作正常,但我不能使用我创建的 jsdoc.json 文件。 { "tags
我仍在学习 js 并试用 Webstorm IDE,它看起来不错(包括跳转到 var/函数声明)。 我可以看到如何让 jsdoc 评论出现的模板,但我没有这方面的经验,正在寻找一个例子来说明如何在评论
我仍在学习 js 并试用 Webstorm IDE,它看起来不错(包括跳转到 var/函数声明)。 我可以看到如何让 jsdoc 评论出现的模板,但我没有这方面的经验,正在寻找一个例子来说明如何在评论
我有两种类型的模块: Require.js 主文件: require.config({ baseUrl: "/another/path", paths: {
是否有任何自然方式或特殊标签将参数类型作为链接? /** * My js app * @module app */ /** * Namespace for MYAPP classes and func
我有一个包含大量选项的函数: /** * Show dialog in a blocking manner. * * @param {object} opts * @param {string
我只需要在包含 .js 文件的 ai 整个目录上运行 jsdoc,我通过发出命令 jsdoc abc.js 对 ubuntu 终端中的单个文件执行此操作,但我需要的是一次将此命令应用于目录中的所有文件
假设我有两个功能,其中一个扩展了另一个。 /** * @abstract * @param {Object} settings * @param {Number} settings.x * @para
/** * @param {String} foo * @param {Number} bar */ 或者 /** * @param {string} foo * @param {numbe
导致JsDoc忽略源链接的最简单方法是什么?我必须定义自己的模板吗? 最佳答案 如果使用默认模板,则使用templates.default.outputSourceFiles设置为false的配置文件
我是一名优秀的程序员,十分优秀!