Javadocを英語で書くときのチートシート
※ SpringなどのJavadocを眺めながら、ドキュメントの書かれ方を抜き出したものです
クラスの説明
動詞から始める
継承したもの
Extension of 親クラス ...
例) Extension of Encoder exposing extra methods relevant in the context of HTTP request or response body encoding.
Utilityなもの
Miscellaneous ... methods.
例) Miscellaneous String utility methods.
メソッドの説明
動詞から始める
Getterっぽいもの
Returnで始める
例) Return the HTTP method of the request.
Getで始める
例) Get decoding hints based on the server request or annotations on the target controller method parameter.
Setter
Setで始める
例) Set the URIResolver used in the transform.
booleanをセットする場合は、Set whether ~にするとよい
例) Set whether the XSLT transformer may add additional whitespace when outputting the result tree.
オブジェクトを生成するもの
Createで始める (Createで作るものはthe じゃなくて a )
例) Create a new JavaMail MimeMessage for the underlying JavaMail Session of this sender. Needs to be called to create MimeMessage instances that can be prepared by the client and passed to send(MimeMessage).
判定するメソッド (戻り値 boolean)
Indicates whether ...
例) Indicates whether the given class can be read by this converter
Can ~ ? (canで疑問文にしてしまうのもあり)
例) Can this Validator validate instances of the supplied clazz?
Check whether ...
if と whether 迷ったら whetherを使っておけば良い。 whether to do 形式が便利
取得する系のバリエーション
Obtain (いくつかの処理ステップを経て値を取り出す/算出するイメージ)
例) Obtain a named parameter from the given request parameters.
Retrieve (箱からスッと取り出すイメージ)
例) Retrieve the first cookie with the given name.
データ変換系
Convert A into B
例) Convert the supplied Object into an XSLT Source if the Object type is supported.
パラメータを説明文で使う場合は、「the given + パラメータ名」で指し示すと良い。
Parametersの説明
名詞で書く
Class
the type of A to B (BするためのAの型という形式で書く)
例) the converted object
処理対象のオブジェクト
the A that is to be B BするためのA
例) the object that is to be validated
Nullを許可しないパラメータ
(never null) を補足に付ける
例) combined output Map (never null), with dynamic values taking precedence over static attributes
パラメータ名にthe付けただけの説明になってしまって、何か寂しいときの修飾子
current
actual
target (「対象の」の意で形容詞として付ける)
Returnsの説明
返すものを名詞で書く
~形式の~ → ... as ...
例) the HTTP method as an HttpMethod enum value
Listを作って返す場合
a List of ...
Arrayを作って返す場合
an array of ...
Mapを作って返す場合
a Map with ...
booleanを返す場合
true if ... (どういう時に真になるかだけ書く)
例) true if that conversion can be performed
nullが返るかもしれないものは、文末に, if anyを付ける
例) Return the user associated with the request, if any.
Throwsの説明
in case of ...
例) IOException - in case of I/O errors ※何の説明にもなってないがこの記述パターンは実際に多い