本文详解如何为普通 JavaScript 对象（非类实例）中的属性和方法添加标准、可被 IDE（如 VS Code）正确识别的 JSDoc 注释，重点解决 @property 在对象字面量中失效、方法参数不显示等问题。

本文详解如何为普通 javascript 对象（非类实例）中的属性和方法添加标准、可被 ide（如 vs code）正确识别的 jsdoc 注释，重点解决 `@property` 在对象字面量中失效、方法参数不显示等问题。

在 JavaScript 中，为对象字面量（object literal）添加高质量 JSDoc 注释，关键在于避免误用 @typedef 定义类型后又重复注释实例——这种模式常导致 IDE 无法关联方法签名，尤其使 @param 和 @returns 在方法调用时不可见。

正确的做法是：直接在对象成员上逐项注释，而非先定义类型再声明实例。JSDoc 工具（如 TypeScript Language Server、VS Code 内置 JS 支持）会自动推导结构，并将方法注释与调用上下文绑定。

以下为推荐写法：

Feishu calendar sync, local ics to json data for AI agent

将ICS日历文件转为JSON格式，用于飞书日历导入导出及数据集成。

下载

/**
 * An object that manages a numeric property with setter logic.
 * @example
 * objectName.set(42);
 * console.log(objectName.property); // 42
 */
const objectName = {
  /**
   * The numeric property of the object.
   * @type {number}
   */
  property: 0,

  /**
   * Sets the `property` to the given value.
   * @param {number} value - The value to assign to `property`.
   * @returns {void}
   */
  set(value) {
    this.property = value;
  }
};

✅ 优势说明：

• @type {number} 明确声明属性类型，支持类型检查与自动补全；
• 方法注释紧贴函数定义，确保 @param 和 @returns 在 objectName.set( 触发时完整显示；
• @example 提供可运行示例，增强文档实用性；
• 无需 @typedef 或 @type {ObjectName} 等间接声明——这些更适合复杂类型复用场景，反而干扰字面量成员的内联解析。

⚠️ 注意事项：

• 不要在对象外部用 @property 描述内部成员（如你最初尝试的 @property {number} property），该标签仅适用于 @typedef 或 @class 的上下文中；
• 若需复用该结构定义多个同类对象，建议改用 class 或 /** @type {Object void}>} */ 类型断言，但牺牲可读性；
• 所有 JSDoc 块必须紧邻对应成员（无空行），否则部分工具可能丢失关联。

总结：面向对象字面量的 JSDoc，应遵循「就近注释、直述语义、类型内联」原则。简洁即强大——正确的位置比复杂的类型定义更能保障开发体验。

Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南