jsdoc构造函数如何正确返回新对象？

Question

例如我有这样的代码：

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,
  }
}

我尝试像这样记录它：

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
   * @lends Person
   */
  const person = {
    /**
     * Name string
     * @type {string}
     */
    get name() {
      return 'Person name is' + name
    },
    age,
    getFullData,
  }

  return person
}

通过这样的代码，我获得了构造函数 createPerson 的正确文档，其中包含指向 Person 的返回类型链接，我在其中看到了它的所有 props 和方法。

但我没有看到 getFullData 和 Age 文档。我尝试过的所有 @borrows 变体都不起作用。 @inheritdocs 也不起作用。如何在不复制文档的情况下获得它？因为在真实的代码中，从构造函数返回的方法太多，文档复制会弄得一团糟，而且复制文档本质上太丑陋了。

Answer 1

我个人会将您的代码直接转换为类，但如果您不想这样做，您可以使用 jsdoc 来定义与类非常相似的内容：

/**
 * @typedef {Object} Person
 * @property {string} name
 * @property {number} age
 * @property {() => string} getFullData
 */

/**
 * @param {string} name
 * @param {number} age
 * @returns {Person}
 */
const createPerson = (name, age) => {
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }
  return {
    get name() {
      return "Person name is " + name
    },
    age,
    getFullData,
  }
}

如果你确实想将其转换为类，我会这样做：

class Person {
  
  #name = '';
  age = 0;
  
  constructor( name, age ){
    
    this.#name = name;
    this.age = age;
    
  }
  
  get name(){
    
    return `Person name is ${this.#name}`;
    
  }
  
  getFullData(){
    
    return `Person ${name} is ${age} years old`;
    
  }
  
}

const createPerson = (name, age) => new Person( name, age );

上述技术很好地自我记录了代码，从技术上讲，您可以完全删除

createPerson

，因为它只是

new Person( name, age )

，因此您不必添加另一层逻辑来创建逻辑层并导出

Person

班。