如何正确为返回新对象的构造函数编写JSDoc文档？

我有如下代码：

export { createPerson }
const createPerson = (name, age) => {
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }
  return {
    get name() {
      return "Person name is " + name
    },
    age,
    getFullData,
  }
}

我尝试用JSDoc为它编写文档：

/**
 * @module people
 */
export { createPerson }
/**
 * Generates a new Person
 * @param {string} name Person name
 * @param {number} age Person age
 * @returns {Person}
 */
const createPerson = (name, age) => {
  /**
   * Gets full data for this person
   */
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }
  /**
   * A Person
   * @constructs Person
   */
  const person = {
    /**
     * Name string
     * @type {string}
     */
    get name() {
      return 'Person name is' + name
    },
    /**
     * @prop {number}
     */
    age,
    /**
     * @method
     */
    getFullData,
  }

  return person
}

目前createPerson的文档能正常生成，返回类型也能链接到Person，但Person下的getFullData和age的文档无法显示。试过@borrows、@inheritDoc都没用，不想复制文档（实际场景中方法很多，复制会造成混乱），该怎么解决？

核心是通过@typedef提前定义Person类型的完整结构，把属性和方法的文档统一写在typedef里，再让内部变量通过@type关联到typedef对应的字段，避免重复编写文档。

方案一：直接在typedef中定义属性文档 #

/**
 * @module people
 */

/**
 * @typedef {Object} Person
 * @property {string} name - 格式化后的人员名称（由getter返回）
 * @property {number} age - 人员年龄
 * @property {function} getFullData - 获取该人员的完整信息
 */

export { createPerson }

/**
 * 生成一个新的Person实例
 * @param {string} name 人员原始名称
 * @param {number} age 人员年龄
 * @returns {Person}
 */
const createPerson = (name, age) => {
  /** @type {Person['getFullData']} */
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }

  const person = {
    get name() {
      return 'Person name is ' + name
    },
    age,
    getFullData,
  }

  return person
}

方案二：用@callback单独定义方法文档（适合复杂方法） #

如果方法需要更详细的文档，可以用@callback单独定义，再关联到typedef中：

/**
 * @module people
 */

/**
 * 获取人员完整信息的方法
 * @returns {string} 返回格式化的人员信息字符串，格式为「Person [名称] is [年龄] years old」
 * @callback PersonGetFullData
 */

/**
 * @typedef {Object} Person
 * @property {string} name - 格式化后的人员名称（由getter返回）
 * @property {number} age - 人员年龄
 * @property {PersonGetFullData} getFullData
 */

export { createPerson }

/**
 * 生成一个新的Person实例
 * @param {string} name 人员原始名称
 * @param {number} age 人员年龄
 * @returns {Person}
 */
const createPerson = (name, age) => {
  /** @type {PersonGetFullData} */
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }

  const person = {
    get name() {
      return 'Person name is ' + name
    },
    age,
    getFullData,
  }

  return person
}

两种方案都能让Person类型的所有属性和方法文档正常显示，同时内部函数的定义和文档关联，不需要重复编写内容。

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