JSDoc：用相互依赖的参数记录函数

Question

我有一个接受两个参数的函数，例如：

function example(type, val) {
  // handle "val" based on "type"
}

val

可接受的类型取决于

type

。

type

参数将始终是几个选择字符串之一。例如，我的 JSDoc 可能如下所示：

/**
 * Handles the value of "val" based on the "type" parameter.
 * @function example
 * @param {"number" | "string" | "boolean"} type - The type of the "val" parameter.
 * @param { ????? } val - The value to handle.
 * @returns {void}
 */
function example(type, val) {
  // handle "val" based on "type"
}

值得注意的是，

"number"

、

"string"

和

"boolean"

实际上并不是我真实代码中

type

的允许值；我在这里仅使用它们进行演示，因为它使问题更容易理解。

如上面的代码所示，

type

可以采用一些选择值。例如，如果

type="number"

，则

val

只能是数字。

我认为我可以将一些 typedef 结合在一起来实现我正在寻找的结果，但我并不完全确定这将如何工作，因为我处理的是函数，而不是对象。

如有任何建议，我们将不胜感激！

Answer 1

有两个答案，取决于您真正想要的。

第一种情况是，如果

value

不是

type

参数中给定的类型，您希望产生 IntelliSense 错误。我建议直接使用这里的类。

第二种情况是你想根据

type

的不同来不同地解析你的值。请注意，在本例中 (

example2

)，我将

type

参数类型保留为

string

。

// 1st case:
/**
 * Handles the value of "value" based on the "type" parameter.
 * 
 * @template { typeof Boolean | typeof Number | typeof String } TYPE
 * @template { InstanceType < TYPE > } VALUE
 * 
 * @param { TYPE } type - The type of the "val" parameter.
 * @param { VALUE } value - The value to handle.
 * 
 * @returns
 */
function example ( type, value )
{
   if ( value instanceof type )
   {
      // Handle the value...
   }
   
   else
   {
      // Ignore or do something else.
   }
}

example(String, 1);
//--------------^
// IntelliSense will shown an error here if @ts-check is enabled.

// 2nd case:
/**
 * Handles the value of "value" based on the "type" parameter.
 * 
 * @param { 'boolean' | 'number' | 'string' } type - The type of the "value" parameter.
 * @param { any } value - The value to handle.
 * 
 * @returns
 */
function example2 ( type, value )
{
   switch ( type )
   {
      case 'boolean':
      default:
      {
        // Handles value as a number.
        break;
      }
      
      case 'number':
      {
        // Handles value as a string.
        break;
      }
      
      case 'string':
      {
        // Handles value as a string.
        break;
      }
   }
}

example2('string', 1);
// Does not show errors.