JSDoc函数返回其自身的参数

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

JSDoc function returning a parameter of itself

问题

Sure, here's the translated code portion you requested:

  1. /**
  2.  * 找到具有给定索引的页面并返回
  3.  *  - 如果不存在，则返回索引
  4.  *  - 如果用户没有阅读权限，则返回用户
  5.  *  - 否则返回页面本身
  6.  * 
  7.  * @param {number} index 
  8.  * @param {string} user 
  9.  * @returns {index|user|Page}
  10.  */
  11. function getRead(index, user) {
  12.     let page = pages.find(page => page.details.index == index);
  13.     if (page && page.canRead(user)) {
  14.         return page;
  15.     } else if (!page) return index;
  16.     else return user;
  17. }

Please note that JavaScript does not support the type of conditional return value you are attempting to document using JSDoc. The @returns tag in JSDoc typically describes the data type that the function returns, but it cannot be used to express conditions like {index|user|Page}.

英文:

I need to document a function returning conditionally one of its parameters. But JSDoc seems not to accept variables as a return value.

I tried to do something like this following the return type {1 | 0} logic

  1. /**
  2.  * Finds the page with given index and returns
  3.  *  - index if it does not exist
  4.  *  - user if user doesn't have permissions to read
  5.  *  - else the page itself 
  6.  * 
  7.  * @param {number} index 
  8.  * @param {string} user 
  9.  * @returns {index|user|Page}
  10.  */
  11. function getRead(index, user) {
  12.     let page = pages.find(page => page.details.index == index);
  13.     if (page && page.canRead(user)) {
  14.         return page;
  15.     } else if (!page) return index;
  16.     else return user;
  17. }

But it is not recognized and the return values is just any, if i use {string|number|Page} as type, afterwards in my code I do something like this

  1. if(page == index) return res.send(`Page ${index} does not exist`);
  2. if(page == user) return res.send(`No permissions to view page ${index}`);
  3. //page still recognized as number | string | Page
  4. //no code completion or property suggestions on page

I also tried to add type checks to get there but i don't want to believe that like such a lazy the solution is the only one, there must be a better way to handle this

  1. if(typeof page == "number" || page == index) return res.send(`Page ${index} does not exist`);
  2. if(typeof page == "string" || page == user) return res.send(`No permissions to view page ${index}`);
  3. //page recognized as Page

答案1

得分: 1

有几种解决方案：

  1. 使用泛型类型作为参数
  1. /**
  2.  * 根据给定的索引查找页面并返回：
  3.  *  - 如果不存在，则返回索引
  4.  *  - 如果用户没有读取权限，则返回用户
  5.  *  - 否则返回页面本身
  6.  * 
  7.  * @template {number} IndexType
  8.  * @template {string} UserType
  9.  * @param {IndexType} index 
  10.  * @param {UserType} user 
  11.  * @returns {IndexType|UserType|Page}
  12.  */
  13. function getRead(index, user) {
  14.  ...
  15. }
  1. 完全移除函数的 JSDoc，依赖 TypeScript 的类型推断
  1. function getRead(/**@type {number}*/index, /**@type {string}*/user) {
  2.   ...
  3. }

JSDoc函数返回其自身的参数

JSDoc函数返回其自身的参数

英文:

There are several solutions:

  1. Use generic types for parameters
  1. /**
  2.  * Finds the page with given index and returns
  3.  *  - index if it does not exist
  4.  *  - user if user doesn't have permissions to read
  5.  *  - else the page itself 
  6.  * 
  7.  * @template {number} IndexType
  8.  * @template {string} UserType
  9.  * @param {IndexType} index 
  10.  * @param {UserType} user 
  11.  * @returns {IndexType|UserType|Page}
  12.  */
  13. function getRead(index, user) {
  14.  ...
  15. }

JSDoc函数返回其自身的参数

  1. Remove JSDoc for the function at all and rely on TypeScript's type inference
  1. function getRead(/**@type {number}*/index, /**@type {string}*/user) {
  2.   ...
  3. }

JSDoc函数返回其自身的参数

huangapple
  • 本文由 发表于 2023年1月5日 16:41:31
  • 转载请务必保留本文链接：https://go.coder-hub.com/75015756.html
  • code-documentation
  • javascript
  • jsdoc
  • node.js
匿名

发表评论

匿名网友

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

确定