JavaScript文档注释深入讲解(非常详细)

/**
 * 这是一个示例函数，用于加法运算。
 * @param {number} a - 第一个操作数
 * @param {number} b - 第二个操作数
 * @returns {number} - 两个操作数的和
 */
function add(a, b) {
  return a + b;
}

// 函数防抖
function debounce(func,duration = 1000) {
  
}

// 函数防抖
function debounce(func,duration = 1000) {
  func.aply
}

// 函数防抖
function debounce(func,duration = 1000) {
}

debounce

// 函数防抖
function wefwfas(func,duration = 1000) {
}

wefwfas

/**
 * 
 * @param {*} func 
 * @param {*} duration 
 */
function wefwfas(func,duration = 1000) {
  
}

/**
 * 函数防抖
 * @param {*} func 
 * @param {*} duration 
 */
function debounce(func,duration = 1000) {

}

debounce()

  * @param {<type>} <param-name> <comments>

/**
 * 函数防抖
 * @param {Function} func 
 * @param {Number} duration 
 */
function debounce(func,duration = 1000) {

}

debounce()

/**
 * 函数防抖
 * @param {Function} func 
 * @param {Number} duration 
 */
function debounce(func,duration = 1000) {
  func.call
}

debounce()

/**
 * 函数防抖
 * @param {Function} func 防抖的目标函数
 * @param {Number} duration 函数执行前等待的时间
 */
function debounce(func,duration = 1000) {

}

debounce()

/**
 * 网络请求
 * @param {object} options 配置对象
 * @param {string} options.url 请求地址
 * @param {'GET'|'POST'} options.method 请求方法
 * @param {object} options.body  
 * @param {object} options.headers  
 */
async function request(options) { }

/**
 * 网络请求
 * @param {object} options 配置对象
 * @param {string} options.url 请求地址
 * @param {'GET'|'POST'} options.method 请求方法
 * @param {object} options.body  
 * @param {object} options.headers  
 */
async function request(options) { }

request()

  * @returns {<type>} <comments>

/**
 * 函数防抖
 * @param {Function} func 防抖的目标函数
 * @param {Number} duration 函数执行前等待的时间
 * @returns {Function} 返回一个防抖的函数
 */
function debounce(func,duration = 1000) {

}

debounce()

  * @author <author-name> <contact-way>

/**
 * 函数防抖
 * @author ISail <370763160@qq.com>
 * @param {Function} func 防抖的目标函数
 * @param {Number} duration 函数执行前等待的时间
 * @returns {Function} 返回一个防抖的函数
 */
function debounce(func,duration = 1000) {

}

debounce()

  * @license <license-info>

/**
 * @license
 * 
 * 项目一 版本1.0.0
 * (c) 2023年 ISail
 * 根据“项目一许可证”发布。
 * 
 * https://www.example.com/licenses/myproject-license
 */

/**
 * @license
 * 
 * 库一 版本2.0.0
 * (c) 2023年 少莫千华无限公司。 保留所有权利。
 * 
 * 这是一款私有软件。严禁未经授权擅自复制或传播本软件或其任何部分。
 * 
 * 如需咨询许可证相关信息, 请联系:
 * 370763160@qq.com
 */

/**
 * @license
 * 
 * 项目一 版本1.0.0
 * (c) 2023年 ISail
 * 根据Apache许可证2.0发布
 * 
 * SPDX-License-Identifier: Apache-2.0
 * 
 * 了解更多信息，请访问:
 * https://www.apache.org/licenses/LICENSE-2.0
 */

/**
 * 函数防抖
 * @author ISail <370763160@qq.com>
 * @license MIT
 * @param {Function} func 防抖的目标函数
 * @param {Number} duration 函数执行前等待的时间
 * @returns {Function} 返回一个防抖的函数
 */
function debounce(func,duration = 1000) {

}

debounce()

/**
 * 获取指定范围内的随机整数
 * @param {number} min 随机数的最小值
 * @param {number} max 随机数的最大值
 * @return {number} 随机数 
 * @example
 * getRange(1, 10); // 获取[1,10]之间的随机数
 */
function getRandom(min, max) { }

getRandom

/**
 * 用户对象
 * @typedef {object} User
 * @property {number} id - 用户ID
 * @property {string} name - 用户名
 * @property {string} email - 用户电子邮箱
 * @property {Date} birthday - 用户生日
 */

/**
 * 获取用户信息
 * @param {number} userId - 用户ID
 * @returns {User} - 返回用户对象
 */
function getUserInfo(userId) {
  // ...
}

const user = getUserInfo(123);
console.log(user.name); // 输出用户的用户名

/**
 * 执行除法运算
 * @param {number} dividend - 被除数
 * @param {number} divisor - 除数
 * @returns {number} - 返回除法结果
 * @throws {Error} 如果除数为0，则抛出错误
 */
function divide(dividend, divisor) {
  if (divisor === 0) {
    throw new Error("除数不能为0");
  }
  return dividend / divisor;
}

try {
  const result = divide(10, 0);
  console.log(result);
} catch (error) {
  console.error(error.message);
}

/**
 * @deprecated 该函数已被废弃，请使用新的 addNumbers 函数代替。
 * 将两个数字相加
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} - 返回相加的结果
 */
function add(a, b) {
  return a + b;
}

/**
 * 将多个数字相加
 * @param {...number} numbers - 要相加的数字列表
 * @returns {number} - 返回相加的结果
 */
function addNumbers(...numbers) {
  return numbers.reduce((sum, number) => sum + number, 0);
}

console.log(add(2, 3)); // 输出: 5

console.log(addNumbers(2, 3, 4)); // 输出: 9

/**
 * 创建一个动物类
 * @class
 */
class Animal {
  /**
   * 构造函数
   * @param {string} name - 名称
   * @private
   */
  constructor(name) {
    this.name = name; // 公共属性
    this._age = 0; // 私有属性，约定以 "_" 开头
    this._weight = 0; // 私有属性，约定以 "_" 开头
  }

  /**
   * 公共方法 - 获取名称
   * @returns {string} - 返回名称
   * @public
   */
  getName() {
    return this.name;
  }

  /**
   * 保护方法 - 获取年龄
   * @returns {number} - 返回年龄
   * @protected
   */
  _getAge() {
    return this._age;
  }
}

/**
 * 创建一个狗类，继承自动物类
 * @class
 */
class Dog extends Animal {
  /**
   * 构造函数
   * @param {string} name - 名称
   */
  constructor(name) {
    super(name);
    this.breed = "unknown"; // 公共属性
  }

  /**
   * 公共方法 - 获取品种
   * @returns {string} - 返回品种
   * @public
   */
  getBreed() {
    return this.breed;
  }

  /**
   * 公共方法 - 获取年龄和名称
   * @returns {string} - 返回年龄和名称的字符串
   * @public
   */
  getAgeAndName() {
    const age = this._getAge(); // 子类可以访问父类的保护方法
    return `Age: ${age}, Name: ${this.name}`;
  }
}

const animal = new Animal("Animal");
console.log(animal.name); // 可以直接访问公共属性 "name"
console.log(animal._age); // 仍然可以直接访问约定为私有的属性 "_age"

const dog = new Dog("Dog");
console.log(dog.name); // 可以直接访问公共属性 "name"
console.log(dog.breed); // 可以直接访问公共属性 "breed"
console.log(dog._getAge()); // 子类可以调用父类的保护方法 "_getAge"
console.log(dog._age); // 仍然可以直接访问约定为私有的属性 "_age"
console.log(dog.getAgeAndName()); // "Age: 0, Name: Dog"

/**
 * 车辆类
 * @class
 */
class Vehicle {
  /**
   * 构造函数
   * @param {string} brand - 品牌
   */
  constructor(brand) {
    this.brand = brand; // 公共属性
  }

  /**
   * 获取品牌信息
   * @returns {string} - 返回品牌信息
   */
  getBrand() {
    return this.brand;
  }
}

/**
 * 汽车类，继承自车辆类
 * @class
 * @extends Vehicle
 */
class Car extends Vehicle {
  /**
   * 构造函数
   * @param {string} brand - 品牌
   * @param {string} model - 型号
   */
  constructor(brand, model) {
    super(brand);
    this.model = model; // 公共属性
  }

  /**
   * @inheritdoc
   */
  getBrand() {
    return super.getBrand();
  }

  /**
   * 获取车辆信息，包括品牌和型号
   * @returns {string} - 返回车辆信息
   */
  getVehicleInfo() {
    const brand = this.getBrand(); // 调用父类的方法
    return `Brand: ${brand}, Model: ${this.model}`;
  }
}

const car = new Car("Toyota", "Camry");
console.log(car.getVehicleInfo()); // "Brand: Toyota, Model: Camry"

/**
 * 用户类
 * @class
 */
class User {
  /**
   * 创建一个用户实例
   * @param {string} name - 名称
   */
  constructor(name) {
    /**
     * 用户名称
     * @type {string}
     */
    this.name = name;

    /**
     * 用户ID，只读属性
     * @type {number}
     * @readonly
     */
    this.id = generateUniqueId();
  }
}

const user = new User("Alice");
console.log(user.name); // "Alice"
console.log(user.id); // 使用只读属性，例如："123456"

user.name = "Bob"; // 可以修改可写属性
user.id = 789; // 尝试修改只读属性，会导致错误

/**
 * 表示一个人的类
 * @class
 */
class Person {
  /**
   * 创建一个人的实例
   * @constructor
   * @param {string} name - 名字
   * @param {number} age - 年龄
   */
  constructor(name, age) {
    this.name = name;
    this.age = age;
  }
}

// 创建一个人的实例
const person = new Person("Alice", 25);
console.log(person.name); // "Alice"
console.log(person.age); // 25

/**
 * 计算两个数字的和
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} 两个数字的和
 * @history
 * - 2021-01-01  初始版本
 * - 2022-05-15  修复 bug：处理负数的情况
 */
function addNumbers(a, b) {
  return a + b;
}

/**
 * 计算两个数字的和
 * @param {number} a - 第一个数字
 * @param {number} b - 第二个数字
 * @returns {number} 两个数字的和
 * @date 2021-01-01 初始版本
 * @date 2022-05-15 修复 bug：处理负数的情况
 */
function addNumbers(a, b) {
  return a + b;
}

/**
 * 函数防抖
 * @author ISail <370763160@qq.com>
 * @license MIT
 * @param {Function} func 防抖的目标函数
 * @param {Number} duration 函数执行前等待的时间
 * @returns {Function} 返回一个防抖的函数
 */
function debounce(func,duration = 1000) { }

/**
 * 获取指定范围内的随机整数
 * @param {number} min 随机数的最小值
 * @param {aa} max 随机数的最大值
 * @return {aaa} 随机数 
 * @example
 * getRange(1, 10); // 获取[1,10]之间的随机数
 */
function getRandom(min, max) { }

/**
 * 网络请求
 * @param {object} options 配置对象
 * @param {string} options.url 请求地址
 * @param {'GET'|'POST'} options.method 请求方法
 * @param {object} options.body  
 * @param {object} options.headers  
 */
async function request(options) { }

npm i -g jsdoc

jsdoc <path>

jsdoc ./