JSDoc

Question

我已经开始使用 JSDoc，到目前为止它很棒，但我想记录我的代码部分，例如 Visual Studio 有 #region.

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

/**
 * Region for calling express routes 
 */

here goes code...

/**
 * End region
 */

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

Answer 1

JSDoc 没有提供类似的选项。 AFAIC 这也很有意义。它对记录 API 或提供一些 IDE' 代码帮助有何帮助？

#region lets you specify a block of code that you can expand or collapse when using the outlining feature of the Visual Studio Code Editor. In longer code files, it is convenient to be able to collapse or hide one or more regions so that you can focus on the part of the file that you are currently working on.

甚至 #region 上的文档也表示这是为了启用特定编辑器的功能。 JSDoc 不受某些编辑器的约束，而是用于帮助 API 文档。通过使用相当方便的编辑器，您不需要这样的注释，而是使用编辑器提供的扩展器（例如 Webstorm，Visual Studio 代码）。

有关所有可用选项，请参阅 http://usejsdoc.org。

您可能希望 "force" 编辑器单独折叠部分代码。这可以通过将其包装在某种语言对象（可在您喜欢的编辑器中折叠）或一对大括号中来实现。但是，如果您将不得不共享此代码，请期待被问及这有什么用处...

Answer 2

SAPUI5: UI Development Toolkit for HTML5 文档讨论了 JSDocs 中 section/banner 注释的陷阱。具体来说：

JSDoc interprets any multiline comment starting with a double asterisks ( /** ) as a documentation comment for the JavaScript symbol that follows the documentation comment. [...] So do not use stars/asterisks for a separating banner comment. You can use other characters, for example

/* ==== */

or

/* ----- */

or at least avoid the double asterisks at the beginning.

JSDoc - 如何记录代码区域

JSDoc - how to document region of code

javascript

comments

regions