Tomcatのバージョンごとのweb.xmlのヘッダー

それぞれバージョンがあってないと一部使用できない機能があるので注意。
※metadata-completeのデフォルト値はfalseで、trueの場合はウェブアプリケーションに関係するアノテーションが読み込まれない。

Tomcat 10.1

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
                      https://jakarta.ee/xml/ns/jakartaee/web-app_6_0.xsd"
  version="6.0"
  metadata-complete="false">

Tomcat 10.0

<web-app xmlns="https://jakarta.ee/xml/ns/jakartaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://jakarta.ee/xml/ns/jakartaee
                      https://jakarta.ee/xml/ns/jakartaee/web-app_5_0.xsd"
  version="5.0"
  metadata-complete="false">

Tomcat 9.X

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
                      http://xmlns.jcp.org/xml/ns/javaee/web-app_4_0.xsd"
  version="4.0"
  metadata-complete="false">

Tomcat 8.X

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
	 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	 xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
	 version="3.1"
         metadata-complete="false">

Tomcat 7.X

<web-app xmlns="http://java.sun.com/xml/ns/javaee"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
           version="3.0"
           metadata-complete="false">

JenkinsのGitプラグインで更新チェックに複数のブランチが引っかかった場合

JenkinsのGitプラグインで更新チェックに複数のブランチが引っかかった場合は複数のブランチに対してそれぞれビルドが走る。

ひとつのビルドタスクに以下のような記述が出て、他のはそれに引きずられてビルドされる感じ。

Multiple candidate revisions
Scheduling another build to catch up with ${project_name}

Java EE 8がそろそろ固まってきたのでJPA 2.2のJavaDocを日本語に翻訳し始めた(2/3完了)

タイトルの通りですが、Java EE 8準拠のJPA 2.2のJavaDocを日本語訳に翻訳し始めてみました。
サブパッケージを残して翻訳できたので変な場所があったら指摘をお願いします。

用語類は結構不安だったので、アンケート取ったけど、まあ、こんな感じなのかなぁという感想。
relationshipは関係と翻訳してたけど、そりゃ関連と翻訳したほうが良いと @aoetkさんから指摘をもらい、修正するかなーと思ってたら、意外とリレーションシップでよいという人が多かったので、そのまま採用。

他にも変な場所があったら教えてください。
https://megascus.github.io/jpa-spec/docs/apidocs/





日本語でのJavaDocの書き方

JavaDocを何で書くの?とか、書き方とかをまとめたページはたくさんありますが、日本語特有の情報が抜け落ちていたり、英語でのJavaDocの書き方を説明するものばかりなので、日本語特有の情報をいくつか書きたいと思います。

なお、JDK 8u144あたりでの挙動です。将来では変わるかもしれません。

JavaDocの書き方の一般的なものを知りたい場合は公式のマニュアルを見るのが一番良いと思います。
https://docs.oracle.com/javase/jp/8/docs/technotes/tools/windows/javadoc.html

サマリー文の後は2つ改行を入れましょう。

/**
 * 一行目はサマリー文としてその処理(クラス、メソッド等)の概要として扱われます。
 *
 * <p>英語では行末に「.」(ピリオド)が入り、JavaDocではピリオドまでを1行目のサマリーとして扱うという処理が入っていますが、
 * 日本語では基本的にピリオドは使用しませんが、「。」も区切り文字として認識してくれるようです。
 * <p>なお、この挙動についてはJavaDocのマニュアルには書いてありません。
 * <p>さらに、マニュアルに書いてない挙動としては、ピリオドの後に空白行が続いたとしてもその後に小文字が続く場合は文末として認識されないようです。
 * 英語の場合は文頭に小文字が来る場合がないからなのでしょうね。
 * 必ず改行させるために2行目には空行を入れておくと良いでしょう。

また、サマリー行の次の行では<p>タグから開始することを推奨します。そちらのほうがサマリーと明確に分かれるのできれいです。
https://github.com/megascus/servlet-spec/blob/translation/src/main/java/javax/servlet/Servlet.java#L98
https://megascus.github.io/servlet-spec/docs/apidocs/javax/servlet/Servlet.html#init-javax.servlet.ServletConfig-
https://github.com/megascus/servlet-spec/blob/translation/src/main/java/javax/servlet/Servlet.java#L124
https://megascus.github.io/servlet-spec/docs/apidocs/javax/servlet/Servlet.html#getServletConfig--

@Throwsには〜の場合と書きましょう。

英語の場合は
@Throws Exception if〜〜
と書くのが良いとされていますが、日本語の場合は
@Throws Exception 〜〜の場合
と書くのがしっくりきました。(Servlet API 4.0を翻訳しての感想)

ですます調で書きましょう。

ドキュメントは誰かに読んでもらうものです。
できる限り丁寧な言葉づかいで書いたほうが喜ばれます。
断定調だと高圧的な感じになってしまいますし、なんかさー、とか、適当な口語をつかわれると読んでてだるいと感じるわけよ。

日本語固有の話ではないけれども

用語は統一しましょう。

例えば、Servlet 4.0のAPIでは以下の用語が同じ意味として使用されていました。

  • Web Server
  • Servlet Container
  • Web Container

判ってる人は同じ物だってわかるけど、初めての人には優しくないですよね。

typoには気をつけよう

Javaを書くためのエディタで日本語を書かなければいけない都合上typoがすごい多くなりやすいです。
MS Wordに一度食べさせる等をして、typoを発見できるように努めるのも良いでしょう。

まとめ

JavaDoc書くのは面倒くさいですが、マニュアルがない製品を使うのが辛いように、JavaDocは書いただけの見返りをAPIの使用者に与えてくれます。
がんばって書きましょう。

Java EE 8がそろそろ固まってきたのでservlet-spec 4.0のJavaDocを日本語に翻訳した

ということで、完了しました。
成果物は以下からどうぞ。

https://megascus.github.io/servlet-spec/docs/apidocs/

今まで英語を読むだけならできると思ってたけどぜんぜん読めてなかったんだなぁという。。。。
ちょっと休んだらもういくつかを勉強もかねて翻訳しても良いのかもしれないと思った。

Windows上のVSCodeのLanguage Support for JavaでJavaDocを見たときに文字化けする

VSCodeのLanguage Support for JavaJavaDocを参照しようとしたときに文字化けすることがあります。
ファイルのエンコードUTF-8で書かれている場合などです。

WindowsではデフォルトのファイルのエンコーディングWindows-31Jですが、Language Support for Javaでは開かれているファイルのエンコーディングではなく、OSのエンコーディングを見に行ってしまうため、文字化けが発生します。

解消方法としてはオプションに以下の記述を追加してあげるだけです。

"java.jdt.ls.vmargs": "${すでに存在するこのオプションの設定} -Dfile.encoding=UTF-8"