JSDoc

撰写时间：2024-01-28

修订时间：2024-01-28

概述

JSDoc是一种为JavaScript代码编写注解的语法。我们可依据该语法在JavaScript代码旁边定注解，然后利用JSDoc工具可自动生成网站页面。并且，许多IDE内嵌了识别JSDoc的功能，在编写代码时可提供即时参考作用。

一个例子

定义一个sum的函数：

/** * Get the sum of two numbers. * @param {number} a - The first number * @param {number} b - The second number * @returns {number} - The sum of two numbers */ function sum(a, b) { return a + b; }

JSDoc注解使用/**开头，以*/结尾。

第2行为函数作用的说明。

第3行、第4行使用@param来注解函数参数。其格式为：

@param [{type}] [name] [-] [Description]

type可为JavaScript的数据类型，如string, Object等等。Description可使用-来更清晰地区分出说明部分。

第5行使用@returns来注解函数返回值。其格式为：

@returns [{type}] [-] [Description]

在NetBeans中，当调用sum函数时，在函数名称上按⇧Shift + ⌘Command + Space键，可显示：

NetBeans info

这样，对该函数的作用、参数、返回值等整体情况一目了然，十分清晰。

参考资源

use JSDoc