如何正确使用JSDoc注释构造函数以返回一个新对象?

huangapple go评论82阅读模式
英文:

How to jsdoc constructor function returning a new object properly?

问题

例如,我有这样的一段代码:

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,我可以看到它的所有属性和方法。

但我没有看到 getFullDataage 的文档。我尝试了所有的 @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

我找到了实现我想要的方法!这是通过 @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 属性。因为 agecreatePerson 代码中没有初始化,所以无法从那里继承它。

英文:

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.

huangapple
  • 本文由 发表于 2023年8月10日 13:31:44
  • 转载请务必保留本文链接:https://go.coder-hub.com/76872873.html
匿名

发表评论

匿名网友

:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:

确定