Netbeans javascript 评论答案

【问题标题】：Netbeans javascript commentsNetbeans javascript 评论
【发布时间】：2011-09-14 01:30:04
【问题描述】：

我最近发现 Netbeans 真的很喜欢 javascript cmets，格式如下：

/** * 这是一个示例评论 * * @param {Number} myParam 关于这个参数的信息 * @return {String} 返回一些示例字符串。 */ 函数样本（信息）{ .. }

这似乎是与 Javadoc 兼容的 cmets，但是是吗？是否有资源定义了可接受的格式？此外，这种注释风格是否与其他 IDE（如 Eclipse）通用？

编辑：我上传了这个截图来说明 Netbeans 如何解释 @param 和 @return

谢谢。

【问题讨论】：

我把你推荐给JSDoc。 :-)

标签： javascript netbeans comments

【解决方案1】：

注释标签与 JSDoc3 类似，但并非所有 JSDoc3 标签都受支持。 JSdocs 3 中缺少一些标签（它们在下面的列表中没有引用）。

您可以通过这种方式查看哪些可用：

以 /** 开始评论并按 Enter 键；
在评论类型@内；
使用 Ctrl + Space (Netbeans) 在 @ 符号后调用代码完成。

它将向您显示支持的标签列表和语法帮助（参数自动完成）。随着用户发布多个错误报告，预计未来的 Netbeans 版本将支持更多标签。

这里是 Netbeans 7.4 支持的标签列表：

@argument// Define argument type, name and description.
@augments // This object adds onto a parent object.
@author// Identify the author of an item.
@borrows// This object uses something from another object.
@class// Use the following text to describe the entire class.
@constant// Document an object as a constant.
@constructor// This function is intended to be called with the "new" keyword.
@constructs// This function member will be the constructor for the previous class.
@default// Document the default value.
@deprecated// Document that this is no longer the preferred way.
@description// Describe a symbol.
@extends // Type object is inherited from.
@字段// A field.
@fileoverview// Describe a file.
@函数// A function.
@ignore// [todo] Remove this from the final output.
@inner// Document an inner object.
@lends// Document properties on an object literal as if they belonged to a symbol with a given name.
@link// Inline tag - create a link.
@memberof// This symbol belongs to a parent symbol.
@name// Document the name of an object.
@namespace// Document a namespace object.
@param// Document the parameter to a function.
@private// This symbol is meant to be private.
@property// Document a property of an object.
@public// This symbol is meant to be public.
@requires// This file requires a JavaScript module.
@return // Return.
@returns// Document the return value of a function.
@see// Refer to some other documentation for more information.
@since// When was this feature added?
@static// Document a static member.
@语法// Explain a syntax.
@throws// Describe what errors could be thrown.
@type// Document the type of an object.
@version// Documents the version number of an item.

【讨论】：

【解决方案2】：

这种风格的cmets是针对JSDoc的。

它与JavaDoc类似，但有一些不同。

您可以通过https://github.com/jsdoc/jsdoc了解更多信息

【讨论】：

没那么快。并非所有 JSDoc 标签都受支持。事实上，目前还不支持一些非常重要的（例如@code）。

【解决方案3】：

通常，文档标准由您的组织或客户制定。如果不是，我倾向于遵循类似于您在 netbeans 中找到的通用标准。

【讨论】：

【解决方案4】：

没关系。 /* 和 */ 之间的所有内容都会被评论。 Netbeans 只是通过在每一行添加* 使它看起来更好。重点是，在Java 和Javascript 中，您可以使用/* ... */-multiline 或// ...-single 行进行评论，而在CSS 中，您只能使用/* ... */。

【讨论】：

-1 这确实很重要。 JSDoc 和 JavaDoc 文档 cmets a) 使用双星号开头 /** 和 b) 定义一组特定的注释，例如 @param、@return、@throws 等，IDE 和这些工具解释这些注释以提供类型- 提示、代码完成和格式化文档。