英文:

How to jsdoc constructor function returning a new object properly?

问题 {#heading}

例如，我有这样的一段代码：

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

我尝试这样对其进行文档化：

/**
 * @module people
 */
export { createPerson }
/**
 * 生成一个新的人员实例
 * @param {string} name 人员姓名
 * @param {number} age 人员年龄
 * @returns {Person}
 */
const createPerson = (name, age) => {
  /**
   * 获取该人员的所有信息
   */
  const getFullData = () => {
    return `Person ${name} is ${age} years old`
  }
  /**
   * 一个人员实例
   * @constructs Person
   */
  const person = {
    /**
     * 姓名字符串
     * @type {string}
     */
    get name() {
      return 'Person name is' + name
    },
    /**
     * 年龄
     * @prop {number}
     */
    age,
    /**
     * 方法
     */
    getFullData,
  }

  return person
}

使用这样的代码，我得到了对构造函数 createPerson 的正确文档，其中返回类型链接到 Person，我可以看到它的所有属性和方法。

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

For example I have a code like this:

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

I tried to document it like this:

/**
 * @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
}

With code like this I get a proper documentation of the constructor function createPerson with the returning type link to Person, where I see all of it's props and methods.

But I don't see getFullData and age documentation. All @borrows variants I tryed didn't work. @inheritdocs don't work either. How can I get it without copying documentation? Because in a real code there are too many methods returned from the constructor and doc-copying will make a mess and it's too ugly by it's essence to duplicate docs.

答案1 {#1}

得分: -1

我找到了实现我想要的方法！这是通过 @borrows 实现的。之前我没有仔细阅读文档 --- 关于 JSDoc 系统中的命名和路径部分。

这里是一个可行的解决方案：

/**
 * @module people
 */
export { createPerson }

/**
 * 生成一个新的人员对象
 * @param {string} name 人员姓名
 * @param {number} age 人员年龄
 * @returns {Person}
 */
const createPerson = (name, age) => {
  /**
   * 获取此人员的完整数据
   * @returns {string}
   */
  const getFullData = () => {
    return `人员 ${name} 今年 ${age} 岁`
  }
  /**
   * @constructs Person
   * @borrows module:people~createPerson~getFullData 作为 getFullData
   */
  const person = {
    /**
     * 姓名文本
     * @type {string}
     */
    get name() {
      return '人员姓名是' + name
    },
    /**
     * @prop {number}
     */
    age,
    getFullData,
  }

  return person
}

现在 getFullData 方法的文档已经被继承了，但我仍然需要记录 age 属性。因为 age 在 createPerson 代码中没有初始化，所以无法从那里继承它。 英文:

I found a way to do what I want! It's @borrows. I just didn't read documentation carefully before --- that part concerning naming and pathing in JSDoc system.
And here is a working solution:

/**
 * @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


  * @returns {string}
    /
    const getFullData = () =\> {
    return `Person ${name} is ${age} years old`
    }
    /*


  * @constructs Person


  * @borrows module:people~createPerson~getFullData as getFullData
    /
    const person = {
    /*


    * Name text


    * @type {string}
      /
      get name() {
      return \'Person name is\' + name
      },
      /*


    * @prop {number}
      */
      age,
      getFullData,
      }








`return person
}
`

Now getFullData method's documentation is inherited, but I still need to document the age prop. Age wasn't initialized in the createPerson code, so I cannot borrow it from there.