JSDoc 是许多代码库中使用的一种流行的内联文档方法。
编写 JSDoc 是为了增强代码的可读性，以及方便导出 API 文档。
JSDoc 是 DocBlock 的 JavaScript 实现，DocBlock 是一种用于各种编程语言（包括 PHP、Ruby 和 Python）的文档方法。
它提供了一种一致且可识别的文档方法。还有几个工具可以根据 JSDoc 注释自动生成文档。
JSDoc 的目的是记录您的 JavaScript 应用程序或库的 API。假设您需要为模块、命名空间、类、方法和方法参数等内容添加注释。
最简单的方法是创建一个带有两个前导星号 ( /**) 的注释，以及对函数功能的描述。
/**
* 将两个数字相加
*/
function add(num1, num2) {
return num1 + num2
}
添加描述很简单，只需在文档注释中键入您想要的描述即可。
特殊的 JSDoc 标签可用于提供更多信息。最常用的是 @param，它描述了一个函数参数，和 @return，它描述了返回的内容。
使用 JSDoc 标签来描述您的代码：
/**
* 将两个数字相加
* @param {Number} num1 要添加的第一个数字
* @param {Number} num2 要添加的第二个数字
* @return {Number} 总数
*/
function add(num1, num2) {
return num1 + num2
}
更多标签可用于添加更多信息。有关 JSDoc 的完整标签列表，请参阅 Block Tags。
添加代码注释后，您可以使用 JSDoc 工具从源文件生成 HTML 网站。
默认情况下，JSDoc 使用内置的默认模板将文档转换为 HTML。您可以编辑此模板以满足您自己的需求，或者创建一个全新的模板。
在命令行上运行文档生成器：
npx jsdoc index.js
此命令将在当前工作目录中创建以 /out 命名的目录。在该目录中，您将找到生成的 HTML 页面。
以上述的代码为例，生成的页面如下：
我相信，很多开发人员都不喜欢写注释。
很多开发人员都追求代码的自我描述性，代码的目的非常明显，不需要文档。
对你来说显而易见的东西可能对阅读你代码的其他人来说并不明显。适当的添加一些注释，可以帮助他们更快、更容易地工作。
好的文档不仅仅描述发生了什么，还描述了为什么要这样做。一年后，当你去看一段时间没有接触过的代码时，你会忘记这些内容。
Document This 是一个 VS Code 扩展，可以自动为 TypeScript 和 JavaScript 文件生成详细的 JSDoc 注释。
另一个不错的 JSDoc 注释扩展 — Add jsdoc comments
本文首发 blog，如果喜欢或者有所启发，欢迎 Star，对作者也是一种鼓励。
我正在尝试使用JsDoc来记录es6类。无法相信您不能将类作为参数传递(类类型，而不是实例类型)。我一直在尝试一些事情，但无法让这个简单的代码正常工作，因此JsDoc不会向我抛出一些警告。除非我为我的每个类创建一个@typedef，然后手动将所有自己的和继承的成员添加到它，否则我无法让它工作。甚至不能做mixin!有没有人成功传递构造函数/类参数？让JsDoc处于静态上下文中，而不是实例上下文中？/***@classA*/classA{/***@static*/statichelloFromClassA(){}}/***@classB*@extendsA*/classBextendsA
我有一个JavaScript单例定义为:/***Adescriptionhere*@class*/com.mydomain.ClassName=(function(){/***@constructor*@lendscom.mydomain.ClassName*/varClassName=function(){};/***methoddescription*@public*@lendscom.mydomain.ClassName*/ClassName.prototype.method1=function(){};returnnewClassName();})();在详细模式(-v)下不打
我正在尝试在jsdoc3.4.2中创建自定义标签。config.json文件是{"tags":{"allowUnknownTags":true,"dictionaries":["jsdoc","closure"]},"source":{"include":["app/"],"exclude":[],"includePattern":".+\\.js(doc|x)?$","excludePattern":"(^|\\/|\\\\)_"},"plugins":["plugins/custom-tags.js"],"templates":{"cleverLinks":false,"monos
JSDoc3的documentation包括这个例子:/***ThecompleteTriforce,oroneormorecomponentsoftheTriforce.*@typedef{Object}WishGranter~Triforce*@property{boolean}hasCourage-IndicateswhethertheCouragecomponentispresent.*@property{boolean}hasPower-IndicateswhetherthePowercomponentispresent.*@property{boolean}hasWisdo
我正在尝试使用JSDoc(EcmaScript2015、WebStorm12Build144.3357.8)记录我的代码。我有一个箭头函数，我想记录它的参数。这两个示例有效(我得到自动完成):/**@param{Number}num1*/vara=num1=>num1*num1;//------------------------------/**@param{Number}num1*/vara=num1=>{returnnum1*num1;};但是当我想在forEach函数中记录箭头函数时，例如，自动完成功能不起作用(以下所有情况):/**@param{Number}num1*/[]
当尝试处理带有流类型注释的js源代码时，jsdoc解析器无法理解增强的语法!有没有一种方法可以在使用流类型注释增强的js源代码中使用jsdoc，或者从类型注释的js生成文档的推荐方法是什么？ 最佳答案 刚开始使用documentation.js.开箱即用地支持JSdoc和流。 关于javascript-在带有流类型注释的js上使用jsdoc，我们在StackOverflow上找到一个类似的问题： https://stackoverflow.com/questi
我有这样的东西:/**DieseKlasseblabla...@constructor**/my.namespace.ClassA=function(type){/**Thisfunctiondoessomething**/this.doSomething=function(param){}}该类将列在生成的文档中。该功能不会。有没有办法告诉JSDoc(3)这是ClassA类的成员函数？ 最佳答案 试试这个!/***DieseKlasseblabla...*@constructor*/my.namespace.ClassA=func
假设我有这样一个类:functionmyClass(q){this.someFunction=function(e){console.log("Clickevent");};jQuery(q).click(this.someFunction);}有没有办法向JSDoc表明someFunction不仅仅是一个应该直接调用的函数，而是一个事件处理程序？我看到了@event标签，但如果我理解正确的话，这更多是为了记录我认为是事件的类中的函数(客户端代码也会注册，并且我的类会在需要时触发)而不是一个事件处理函数？ 最佳答案 关键词是@lis
我正在尝试记录一个函数生成器但没有成功，这是一个例子:functiongenericObjectGenerator(tagname){varspecificObject=function(){};specificObject.getClassName=function(){returntagname;}specificObject.prototype.sayHello=function(name){returntagname+"sayshelloto"+name;}returnspecificObject;}varMyObject=genericObjectGenerator("obj
我希望内联评论尽可能短，因为我的经验是超过3或4行的评论往往被掩盖，造成很多不必要的“阅读手册行”。遗留要求我遵守与jsdoc兼容的格式来记录代码。如果要正确记录很多不言而喻的事情，就需要明确声明。实际上每个标签都属于这一类。即使是那些没有的对于工作的开发人员来说通常也是无用的。我的愿景是在代码本身内有一个开发人员实际阅读的快速摘要，但引用一个单独的文件(或者甚至是同一文件中的评论转储，与开发人员工作的地方分开)以进行额外标记，像这样:/***Usedwhenmakinganexampleoftheargument.*@includesomeotherplace*/functionex