英文:
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
,我可以看到它的所有属性和方法。
但我没有看到 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
我找到了实现我想要的方法!这是通过 @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.
通过集体智慧和协作来改善编程学习和解决问题的方式。致力于成为全球开发者共同参与的知识库,让每个人都能够通过互相帮助和分享经验来进步。
评论