74483


例えば以下のようにカリー化された関数のJSDocはどのように記述すればよいのでしょうか？

[code]

    export const someCurriedFunction = (arg1: number) => (
      arg2: number,
      arg3: number
    ) => (arg1 + arg2 + arg3);
    
[/code]


CC BY-SA 4.0
2021-03-03T23:21:15.397
74402
2021-03-07T06:25:30.963
2021-03-06T07:24:46.427
19110
44198
question
javascript typescript
カリー化された関数のJSDocの記述方法がわからない


カリー化で困るというよりかは、高階関数をどう書くかで困るように思います。質問文のソースコードは TypeScript と思われますが、素の
JavaScript でも状況はさほど変わらないので特に区別せず回答してみます。

まず大前提として、私の知る限り、この問題に関する綺麗な解決法はまだ存在しないはず……です。実際 JSDoc の issue tracker でもこの問題が
open のまま残っています: <https://github.com/jsdoc/jsdoc/issues/1286>。

とはいえ workaround はあるので、この回答ではそれを紹介します。環境は JSDoc 3.6.6 です。

## 関数扱いした上で、引数や返り値を関数として書く

[`@function`](https://jsdoc.app/tags-function.html)
で関数扱いした上で、通常の関数のように引数と返り値についてアノテーションします。この際、今回の場合は返り値が関数になっていることに注意が必要です。

[code]

    /**
     * Returns the sum of three numbers. The first argument is curried.
     *
     * @function
     * @param {number} arg1 The first argument
     * @returns {function(number, number): number} A function which takes two more numbers and returns the sum of three
     */
    export const someCurriedFunction = ...
    
[/code]

※ここでは <https://jsdoc.app/tags-type.html> に従って型の記法を [Google Closure Compiler
type expression](https://github.com/google/closure-compiler/wiki/Types-in-the-
Closure-Type-System) に則って書いています。場合によっては TypeScript の記法で書いても大丈夫です。

`jsdoc` コマンドにかけると下のようなドキュメントを生成します。返り値が function としか表示されないところが微妙ではあります。

> [![JSDoc の内容が見やすく表示されています。特に arg1 については内容が表として表示されています。返り値については function
> としか書かれていません。](https://i.stack.imgur.com/EKQ0x.png)](https://i.stack.imgur.com/EKQ0x.png)

## 関数値の入った変数としてドキュメントを書く

TypeScript のドキュメントに書かれている方法です:
<https://www.typescriptlang.org/ja/docs/handbook/jsdoc-supported-types.html>。

`someCurriedFunction` は関数型を持つ変数なので、その型でアノテーションすることができます。とはいえ TypeScript
をお使いなのであれば既に TypeScript 側で型が付いているので、`@type` を使う必要は殆どありません。それよりも説明文を書く方が重要でしょう。

[code]

    /**
     * Returns the sum of three numbers. The first argument is curried.
     *
     * @type {function(number): function(number, number): number}
     */
    export const someCurriedFunction = ...
    
[/code]

実際に `jsdoc` コマンドにかけてみると下のように説明文以外ほとんど情報の無いドキュメントが生成されます。

>
> [![](https://i.stack.imgur.com/JnIPO.png)](https://i.stack.imgur.com/JnIPO.png)


CC BY-SA 4.0
2021-03-07T06:25:30.963
74483
2021-03-07T06:25:30.963
19110
74402
answer