Javascript 文档注释！！管理自己的函数和JSON

什么是文档注释

文档注释（Document Comment），也称为文档说明或文档化注释，是一种在计算机程序源代码中用于描述函数、类、方法或变量的注释风格。它的主要目的是提供有关代码功能、用法和设计意图的详细说明，以便其他开发人员能够更好地理解和使用代码。

文档注释通常采用一种特定的格式或标记语言，以区别于常规的代码注释。这样的注释通常会包含以下内容：

描述：对于函数、类、方法或变量的简要描述，包括其目的、功能和作用。
参数：如果是函数或方法，文档注释通常会列出输入参数的名称、类型和描述。
返回值：如果是函数或方法，文档注释通常会说明返回值的类型和含义。
异常：如果是函数或方法，文档注释通常会列出可能抛出的异常或错误情况。
示例：文档注释中通常包含代码示例，以展示如何正确使用函数、类、方法或变量。

文档注释的好处是可以提供一个统一的、易于阅读和理解的文档，可以帮助其他开发人员快速了解和使用代码，减少代码的维护成本和理解难度。常见的文档注释工具包括Javadoc（用于Java）、Pydoc（用于Python）和Sphinx（用于多种语言）等。

为什么我们使用文档注释

首先他不是一种强制的代码规范，但是一种良好的编程实践，但并非强制要求。在编写代码时，根据项目需求和团队约定，决定是否使用文档注释以及如何编写文档注释。

使用了文档注释帮我们解决了那些问题

当我们写完某些功能模块的时候，当中定义了很多的函数和数据，再过个几个月或者几周再对这个模块进行迭代开发的时候，会发现当时定义的函数或者数据忘记了是做什么的，用来处理那些事情的，这个时候如果说这个函数或者数据，再使用的时候出现了使用说明，对参数和返回值描述、使用示例、又清晰的写明，这个让我们再使用的话就会方便很多。

当在JavaScript中编写文档注释时，通常使用特定的注释风格和标记来描述参数。以下是常用的注释参数及其写法和使用方式的示例

/**
* 函数名称
*
* 函数的描述和功能说明。
*
* @param {类型} 参数名 - 参数描述
* @param {类型} 参数名 - 参数描述
* @returns {类型} 返回值描述
* @throws {异常类型} 异常描述
*
* @example
* // 使用示例
* functionName(参数值);
*
* @notes
* 注意事项和其他相关信息
*/

函数名称：替换为实际的函数名称。
函数的描述和功能说明：用简洁的语句描述函数的作用和功能。
@param {类型} 参数名 - 参数描述：用于描述函数的参数。将类型替换为实际参数的类型，参数名替换为参数的名称，参数描述用简洁语句描述参数的作用和含义。如果函数有多个参数，可以重复此行。
@returns {类型} 返回值描述：描述函数的返回值。将类型替换为实际返回值的类型，返回值描述用简洁语句描述返回值的含义。
@throws {异常类型} 异常描述：描述函数可能抛出的异常情况。将异常类型替换为实际异常的类型，异常描述用简洁语句描述异常的含义。如果函数可能抛出多个异常，可以重复此行。
@example：用于提供代码的使用示例。
functionName(参数值);：在代码块中展示使用函数的示例，将参数值替换为实际的参数值。
@notes：用于列出注意事项和其他相关信息。

参数、返回值、异常的类型

常见的参数类型（@param {类型} 参数名 - 参数描述）：

string：字符串类型
number：数字类型
boolean：布尔类型
object：对象类型
array：数组类型
function：函数类型
null：空值类型
undefined：未定义类型
*: 所有类型
自定义类型：根据实际情况，可以使用自定义类型名称来描述参数类型

常见的返回类型（@returns {类型} 返回值描述）：

string：字符串类型
number：数字类型
boolean：布尔类型
object：对象类型
array：数组类型
function：函数类型
null：空值类型
undefined：未定义类型
*: 所有类型
自定义类型：根据实际情况，可以使用自定义类型名称来描述返回值类型

常见的异常类型（@throws {异常类型} 异常描述）：

Error：通用的错误类型
TypeError：类型错误
ReferenceError：引用错误
SyntaxError：语法错误
RangeError：范围错误
EvalError：eval 函数错误
URIError：URI 处理错误
自定义异常类型：根据实际情况，可以使用自定义的异常类型名称来描述特定的异常情况

这些类型是常见的类型示例，实际上，在JavaScript中，类型可以更具体和复杂。根据你的代码和需求，你可以根据需要自定义和使用更多的类型。

如果你的参数是一个对象（Object）或数组（Array），而且内部还有参数需要描述，你可以在文档注释中使用嵌套的注释格式来说明内部参数。下面是一个示例：

/**
* 函数名称
*
* 函数的描述和功能说明。
*
* @param {Object} 参数名 - 参数描述
*   @param {类型} 参数名 - 参数描述
*   @param {类型} 参数名 - 参数描述
* @param {Array} 参数名 - 参数描述
*   @param {类型} 参数名 - 参数描述
*   @param {类型} 参数名 - 参数描述
* @returns {类型} 返回值描述
* @throws {异常类型} 异常描述
*
* @example
* // 使用示例
* functionName({
*   参数名: 值,
*   内部对象参数: {
*     参数名: 值,
*     参数名: 值
*   },
*   参数名: [值, 值, 值]
* });
*
* @notes
* 注意事项和其他相关信息
*/