JSDoc - 如何记录代码区域

Question

JSDoc - 如何记录代码区域

4

我开始使用JSDoc，到目前为止它非常好用，但我想像Visual Studio一样记录我的代码的一部分，使用#region指令。

我是否应该将其包装在注释块中，就像这样？

/**
 * Region for calling express routes 
 */

here goes code...

/**
 * End region
 */

我只是在寻找更优雅的方法来完成这个操作。

- Aren Hovsepyan

2个回答

2

JSDoc没有提供类似的选项，据我所知，这也没有多少意义。它有助于记录API或为某些IDE提供代码辅助吗？在使用Visual Studio Code编辑器的概述功能时，#region允许您指定一个代码块，您可以展开或折叠该代码块。在较长的代码文件中，能够折叠或隐藏一个或多个区域非常方便，这样您就可以专注于当前正在处理的文件部分。即使是#region的文档也说明了这是为了启用特定编辑器的功能。JSDoc并不绑定到某个编辑器，而是用于帮助API文档编写。通过使用相当方便的编辑器，您不需要这样的注释，而是使用编辑器提供的展开器（例如Webstorm、Visual Studio Code）。请参见 http://usejsdoc.org 以获取所有可用选项。您可能想要“强制”编辑器单独折叠代码的某个部分。这可以通过将其包装在某个语言对象（可在您喜欢的编辑器中折叠）或一对大括号中来实现。但是，如果您必须分享此代码，请期待被问及其用途...

- Thomas Urban

你说得对，我正在使用Sublime编辑器，但是我不喜欢自己用//的注释风格，所以决定使用jsdoc，这样阅读起来更整洁，而且我可以为我的应用程序生成文档。 - Aren Hovsepyan

网页内容由stack overflow 提供, 点击上面的

可以查看英文原文，
原文链接

- Graham P Heath · Accepted Answer

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

JSDoc将任何以双星号（/**）开始的多行注释解释为将跟随注释的JavaScript符号的文档注释。 [...] 因此，不要使用星号/星号来分隔标题注释。您可以使用其他字符，例如

/* ==== */

or

/* ----- */

或者至少避免在开头使用双星号。