公開しているライブラリほどじゃないにせよ、チームで開発しているTypeScriptで書いたコードにちらほらドキュメンテーションしていきたい。
それESLintで
とりあえず今までろくに書いていなかった部分はいまさっき書き足すPull Requestを作ったけれど、今後手を入れる時にもちゃんと書いていってほしい。
で、こういうルールの徹底を人間がレビューで「ドキュメントおねがいします」って言うのは不毛。2020年代にやっていいことではない。
TypeScript/JavaScriptでやろうとなったらESLintでどうにかしたい。eslint-plugin-jsdocがJSDocに関連したルールを提供している。
JSDocはTSDocと基本的なフォーマットは同じで細かいタグのセマンティクスは差異がありそう。
そしてなんとeslint-plugin-jsdocはTypeScriptもサポートしている *1。
ちなみにTypeScriptでドキュメント書く時はけっきょくどのフォーマットがええんや (なんかesdocっていうのもあったような) と思っていたらちょうど良いところに:
blog.pokutuna.com
最高。
ほどほどに始めたい
とはいえ社内でのみ開発されるアプリケーションのドキュメントをがちがちに書けというのも大仰なルールだし、そもそもTypeScriptで担えている型情報とかは書かなくて良いということにしたい。
前者は公開されたシンボルにだけドキュメントが書いてあれば良いということでよさそう。公開というのはexportされている、もしくは可視性がpublicであるフィールド・メソッドという定義にする。
eslint-plugin-jsdocにはそのものずばりpublicOnlyというオプションがrequire-jsdocルールにある。
そんなこんなで始めたESLintのルールが以下:
"eslintConfig": { "extends": [ "eslint:recommended", "plugin:@typescript-eslint/eslint-recommended", "plugin:@typescript-eslint/recommended", "plugin:@typescript-eslint/recommended-requiring-type-checking", "plugin:jsdoc/recommended" ], "plugins": [ "@typescript-eslint", "jsdoc" ], "parser": "@typescript-eslint/parser", "env": { "node": true, "es6": true }, "parserOptions": { "ecmaVersion": 2018, "sourceType": "module", "createDefaultProgram": true, "project": "./tsconfig.json" }, "rules": { "jsdoc/require-jsdoc": [ "error", { "publicOnly": true, "require": { "ArrowFunctionExpression": true, "ClassDeclaration": true, "MethodDefinition": true }, "checkConstructors": false } ], "jsdoc/require-param-type": 0, "jsdoc/require-returns": 0 }
*1:大半のルールにおいては。一部のルールはまだサポートされていない