JSDoc with和Immutable.js注释中的数据结构 [英] JSDoc with and Immutable.js datastructures in annotations

问题描述

我从函数返回Immutable.js 列表数据结构。

I am returning Immutable.js List data structure from function.

PHPStorm自动附加
@returns {* | List< T> | List< any>} 。

PHPStorm is automatically attaching following @returns {*|List<T>|List<any>}.

Eslint给我警告T类型的未解决变量。
我在哪里可以找到Immutable.js注释的文档？

Eslint is giving me warning Unresolved variable of type 'T'. Where can I find documentation to annotations for Immutable.js?

如何在列表的@returns中描述将在Eslint中传递的注释形状？

How can I describe in @returns annotation shape of the List that would pass in Eslint?

/**
 * @param n
 * @returns {*|List<T>|List<any>}
 */
const getList = (n) => {
  let list = Immutable.List()

  for (let i = 0; i < n; i++) {
    for (let j = 0; j < n; j++) {
      list = list.push(Immutable.List.of(i, j))
    }
  }

  return list
}

推荐答案

虽然我不熟悉Immutable.js，问题是 T 是必须在文档中定义的模板。看看，你的函数真正返回的是一个数字列表列表。所以 T 解析为列表< Number> ，您的固定文档将类似于：

Although I am not familiar with Immutable.js, the problem is that T is a template that must be defined in your documentation. See, what your function is really returning is a List of List of numbers. So T resolves to List<Number> and your fixed documentation would be something like:

/**
 * @param {Number} n
 * @return {List<List<Number>>}
 */

你可以摆脱 * 和列出< any> 作为可能的返回类型，因为您的函数显然总是返回一个数字列表列表。

And you can just get rid of * and List<any> as possible return types, since your function is clearly always returning a list of list of numbers.

就是这样。

另外请注意，您编写了一个函数，其处理时间与参数 n 呈二次方式增加。如果您发现自己经常调用传递相同值的函数，请考虑记住它的返回值：

On a side note, please bear in mind that you wrote a function whose processing time increases quadratically with the parameter n. If you find yourself frequently calling the function passing the same value, consider memoizing its return value:

const memoizedLists = new Map();

/**
 * @param {Number} n
 * @return {List<List<Number>>}
 */
function getList(n) {
    // try to find a previous run for this same value
    let result = memoizedLists.get(n);

    if (!result) {
        // compute it otherwise
        result = Immutable.List();

        for (let i = 0; i < n; i++) {
            for (let j = 0; j < n; j++) {
                result.push(Immutable.List.of(i, j));
            }
        }

        // memoize it for a future invocation
        memoizedLists.set(n, result);
    }

    return result;
}

此外，不仅时间而且内存使用也以二次方式增加。根据你使用它的方式，你可能想把你的函数变成一个生成函数，这将神奇地使它使用恒定的空间，即无论多大 n 获取，你的函数将继续使用相同数量的内存。这里你的函数变成了生成函数：

Moreover, not only time but memory use is also increasing quadratically. Depending on how you're using it, you probably want to make your function into a generator function instead, which will "magically" make it use constant space, i.e., no matter how big n gets, your function will continue to use just the same amount of memory. Here's your function turned into a generator function:

/**
 * @generator
 * @param {Number} n
 * @yields {List<Number>}
 */
function *getList(n) {
    for (let i = 0; i < n; i++) {
        for (let j = 0; j < n; j++) {
            yield Immutable.List.of(i, j);
        }
    }
}

能够使用它作为发电机，您需要按需调用它。例如，如果您将这些数字对打印到某个输出：

To be able to use it as a generator, you need to call it on demand. For instance, if you're printing those pairs of numbers to some output:

for (const pair of getList(4)) {
    console.info(`...and here comes another pair: [${pair}]`);
}

这篇关于JSDoc with和Immutable.js注释中的数据结构的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！