JSDoc - 如何记录代码区域

Question

我已经开始使用 JSDoc，到目前为止这是一件很棒的事情，但我想像 Visual Studio 那样记录我的代码部分

#region

。

我应该把它包装在这样的评论块中吗？

/**
 * Region for calling express routes 
 */

here goes code...

/**
 * End region
 */

我只是在寻找更优雅的方法来做到这一点。

Answer 1

SAPUI5：HTML5 UI 开发工具包文档讨论了 JSDocs 中部分/横幅注释的陷阱。具体来说：

JSDoc 将以双星号 ( /** ) 开头的任何多行注释解释为文档注释后面的 JavaScript 符号的文档注释。 [...] 因此，请勿使用星号/星号作为分隔横幅评论。您可以使用其他字符，例如

/* ==== */

或

/* ----- */

或者至少避免开头的双星号。

Answer 2

JSDoc 没有提供类似的选项。恕我直言，这也没有多大意义。它对于记录 API 或提供一些 IDE 代码辅助有何帮助？

#region

 允许您指定在使用 Visual Studio 代码编辑器的大纲功能时可以展开或折叠的代码块。在较长的代码文件中，能够方便地折叠或隐藏一个或多个区域，以便您可以专注于当前正在处理的文件部分。

甚至

#region

上的文档也指出这是为了启用特定编辑器的功能。 JSDoc 不绑定到某些编辑器，而是帮助处理 API 文档。通过使用相当方便的编辑器，您不需要此类注释，而是使用编辑器提供的扩展器（例如 Webstorm、Visual Studio Code）。

请参阅

http://usejsdoc.org 了解所有可用选项。

您可能想“强制”编辑器单独折叠代码的某些部分。这可以通过将其包装在某种语言对象（可在您最喜欢的编辑器中折叠）或一对大括号中来实现。但是，如果您必须共享此代码，预计会被问到这有什么用......