如何为TypeScript接口编写规范的JSDoc注释？

下面是针对你提供的三个接口编写的规范JSDoc注释，兼顾可读性和TypeScript类型提示的兼容性：

/**
 * 模态框组件的配置参数接口
 * 用于定义模态框的显示状态与操作方法
 */
export interface IModal {
  /** 模态框关闭时触发的回调函数 */
  onClose: () => void;
  /** 控制模态框是否显示的状态标记 */
  isOpen: boolean;
  /** 当前选中项的唯一标识ID */
  id: number;
  /** 执行选中项删除操作的函数 */
  deleteSelectedId: () => void;
  /** 标记当前模态框是否为部门相关场景 */
  isDepartment: boolean;
}

/**
 * 账户信息的数据结构接口
 * 存储用户的基本身份信息与所属部门信息
 */
export interface IAccountsValue {
  /** 用户的名字 */
  name: string;
  /** 用户的姓氏 */
  surname: string;
  /** 用户的中间名（无则留空） */
  middlename: string;
  /** 用户所属的部门名称 */
  department: string;
  /** 用户的唯一标识ID，未分配时为null */
  id: number | null;
}

/**
 * 带ID的键值对数据接口
 * 用于存储包含唯一标识的名称-值映射项
 */
export interface IGetValue {
  /** 项的名称描述 */
  name: string;
  /** 项对应的实际值 */
  value: string;
  /** 项的唯一标识ID */
  id: number;
}

核心编写规范 #

• 接口整体注释：用/** ... */包裹，清晰说明接口的用途、适用场景，让其他开发者快速理解接口定位。
• 属性注释：每个属性上方单独添加单行注释，精准描述属性的含义、用途，对有特殊取值（如id可为null）的属性要明确说明边界情况。
• 简洁精准：避免冗余表述，注释只补充TypeScript类型无法表达的语义信息，不用重复类型定义。
• 统一风格：保持注释语气、格式一致，提升代码整体可读性。

内容的提问来源于stack exchange，提问作者Anton