🧊

現存するJSDocタグのまとめ

まとめたいなと思ったが、それは叶わぬ夢なのかもしれない・・・。

JSDoc.app

Use JSDoc: Index https://jsdoc.app/#block-tags

JSDocの本家(のはず)で、用途は主にドキュメント作成。

以下がその一覧で、AtoZ(エイリアスは別)順。

まずはブロックタグといわれるよく見るもの。

@abstract
@virtual
@access <package|private|protected|public>
@alias <aliasNamepath>
@async
@augments <namepath>
@extends <namepath>
@author <name> [<emailAddress>]
@borrows <that namepath> as <this namepath>
@class [<type> <name>]
@constructor [<type> <name>]
@classdesc <some description>
@constant [<type> <name>]
@const [<type> <name>]
@constructs [<name>]
@copyright <some copyright text>
@default [<some value>]
@defaultValue [<some value>]
@deprecated [<some text>]
@description <some description>
@desc <some description>
@enum [<type>]
@event <className>#[event:]<eventName>
@example <caption>
@exports <moduleName>
@external <fExternal>
@host <NameOfExternal>
@file <some text>
@fileoverview <some text>
@overview <some text>
@fires <className>#[event:]<eventName>
@emits <className>#[event:]<eventName>
@function [<FunctionName>]
@func [<FunctionName>]
@method [<FunctionName>]
@generator
@global
@hideconstructor
@ignore
@implements {typeExpression}
@inheritdoc
@inner
@instance
@interface [<name>]
@kind <class|constant|event|external|file|function|member|mixin|module|namespace|typedef>
@lends <namepath>
@license <identifier>
@listens <eventName>
@member [<type>] [<name>]
@var [<type>] [<name>]
@memberof <parentNamepath>
@memberof! <parentNamepath>
@mixes <OtherObjectPath>
@mixin [<MixinName>]
@module [[{<type>}] <moduleName>]
@name <namePath>
@namespace [[{<type>}] <SomeName>]
@override
@package
@param [{type}] <name> <description>
@arg [{type}] <name> <description>
@argument [{type}] <name> <description>
@private
@property [<type>] <name> <description>
@prop [<type>] <name> <description>
@protected
@public
@readonly
@requires <someModuleName>
@returns [{type}] [description]
@return [{type}] [description]
@see <namepathOrText>
@since <versionDescription>
@static
@summary <some text>
@this <namepath>
@throws [{<type>}] [<description>]
@exception [{<type>}] [<description>]
@todo <some text>
@tutorial <some text>
@type {typeName}
@typedef [{<type>}] <name> <description>
@variation <variationNumber>
@version <some version number>
@yields [{type}] [description]
@yield [{type}] [description]

(多すぎるし、見たことも聞いたことないのもある。)

それ以外に、インラインタグといってテキスト部に入れられるものが以下。

  • @link
    • @linkcode, @linkplain
  • @tutorial

調べてみると、これで全てかと思いきやそうではない。

ドキュメントは更新されてないのか、コード中には定義されてるものが他にもある。

  • @callback <namepath>
  • @modifies {type}

など。

あとはインターナルなものもあるらしい・・・。

https://github.com/jsdoc/jsdoc/blob/91a9ce02b0237e78fe7345bed6cbcc4afe44cdb6/packages/jsdoc-tag/lib/definitions/internal.js

JSDoc TS

TypeScript: Documentation - JSDoc Reference https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html

JSDoc記法でTypeScriptの型を記述するためのもの。

すべてがサポートされてるわけではなく、一部のみサポートらしい。

@type
@param
@arg
@argument
@returns
@return
@typedef
@callback
@template
@satisfies
@public
@private
@protected
@readonly
@override
@extends
@augments
@implements
@class
@constructor
@this
@deprecated
@see
@link
@enum
@author

ほとんどは既知のものだが、@satisfiesみたく新入りも見受けられる。

あとこのページにはリストされてないけど、@overloadなんかも増えてる。

Closure

JSDocではないけど、Closure Compilerのアノテーションもあり、もはや見分けがつかない!

Annotating JavaScript for the Closure Compiler · google/closure-compiler Wiki https://github.com/google/closure-compiler/wiki/Annotating-JavaScript-for-the-Closure-Compiler

まとめきれないのでリンクだけ。

その他

思いつく限りでは、@jsxとか?

こういうのもあった。

その他にも、独自に開発されて世に流通してるものもあるやろうし、もはや@xxxって付いてたらなんでもJSDocなのか?っていう本質的な問もあるな・・・。

言いたいこと

パースするの地獄すぎる。

結局のところただのコメントなので、誰でも自作タグは作れるし、エイリアスを作ってる実例もある。

https://github.com/gajus/eslint-plugin-jsdoc/blob/783b4e96eef457715a0bce234730da7bb5ec1a3b/docs/settings.md#user-content-settings-alias-preference

パースしたいなら、やっぱただのテキストとして処理して、用途ごとに目的の値を探せるようにするのが妥協点かな・・・。