日本語での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 JavaでJavaDocを参照しようとしたときに文字化けすることがあります。
ファイルのエンコードがUTF-8で書かれている場合などです。

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

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

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

Java EE 8がそろそろ固まってきたのでservlet-spec 4.0のJavaDocを日本語に翻訳し始めた(現在半分完了)

タイトルの通りですが、Java EE 8準拠のservlet-spec 4.0のJavaDocを日本語訳に翻訳し始めてみました。
どうにか半分を越したのでとりあえず公開。
ちまちまやって来月中ぐらいには全部翻訳できそうな感じ。

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

感想

割と後悔している。
ものすごく古い仕様で策定されてまったくJavaDocが更新されていないCookieクラスとか、コピペで作成されたものの差分の修正が甘く明らかに間違った文章になっているFilterやそのサブクラスやそもそも英語としておかしい気がするPushBuilderを筆頭にし、JavaDocタグの使い方を知らないのか？と思われるクラスやら、このドキュメントはサーブレットコンテナのユーザーに向けて書いたのかサーブレットコンテナ自体の実装者に向けて書いたのかがごっちゃになってて非常に難解になっているクラスやらが混ざってて本当にこれはspecなのか・・・・・・？という感じ。

一応githubに上がってたservlet-specの4.0をフォークして作業を始めたのですが、間違ってるのか・・・・・・？
https://github.com/javaee/servlet-spec

といいつつ、まあ、半分は終わってしまったのであと半分も頑張りたい。


ちなみに、今は屈指の勉強会ブームで、その場ではいいだろうけど、資料価値としては低いチュートリアルを日本語化しただけのようなパワーポイントの資料が山ほどできていますが、こういった数年は使われるような大本のドキュメント類を翻訳するような作業に興味がある人はいないんでしょうか？
例えば他のJava EEのJavaDocも日本語化されるだけでも非常に有用だと思うのですが。

JPAのJavaDocとか日本語訳してくれる人いないかなー。
翻訳してくれる人が居るならいくらでも手伝います。

githubで雑にビルド後の成果物を配る

githubではgithub pagesという機能を使ってウェブサイトを公開することができる。
travis-ciというサービスでは無償でビルドを行いgithub pagesにpushをすることができる。

ということで。


github pagesとしての公開の仕方は以下からproject siteを選ぶことで見ることができる。
https://pages.github.com/

travis-ciからgithub pagesにpushするやり方は以下のページ。
https://docs.travis-ci.com/user/deployment/pages/
※githubではgh-pagesというブランチを作成することでgithub pagesに公開することができる(設定が必要)
※gh-pagesブランチを作成していない場合、公開対象として表示されないので注意

Oracle JDBC DriverのJava 8対応版が出ました！(Java 7以前のJDBCドライバは配られなくなった模様)

ついに、Oracle Database 12.2.0.1 からjdbcドライバにJava 8対応版が出ました。(今更かよ)
今まではJava 8から増えたjdbcの新しいメソッド類が実装しなくてもよい（実装されない場合、SQLFeatureNotSupportedExceptionが投げられることがドキュメント化されてしまっていた）ため、Java 7のjdbcドライバの使用を強いられていましたが、ついにJava 8から増えたメソッドも使用することができるようになります。

ダウンロードは以下から
http://www.oracle.com/technetwork/database/features/jdbc/jdbc-ucp-122-3110062.html

ちなみに、増えたメソッドには、PreparedStatementで渡すSQLTypeが今まではintだったのをクラスを渡せるようにしたバージョン等があり、型安全なプログラミングがしやすくなっています。
PreparedStatement

なお、地味につらそうなのが、Java 7以前のjdbcドライバが配られなくなったあたり。これは、Java 7以前は全滅なのでは・・・・・

＊追記ここから＊
とりあえずは過去バージョンのJDBC driverで新しいバージョンのDBに接続できることは保証されるようです。
http://www.oracle.com/technetwork/database/enterprise-edition/jdbc-faq-090281.html#01_02
次のバージョンでJava 8版しかでないのか、それ以前のも一緒に出るのか次第といったところ？


＊追記ここまで＊
＊追記２ここから＊
全部詳しく書いてあった！
＊追記２ここまで＊


という感じで。

Tomcat 8にantからリモートデプロイする

今更antかよ！というつっこみは置いておいて、
Webに残っているドキュメント類がことごとく古くて使用できなかったので更新メモとして。

1. antのフォルダにTomcatから以下のライブラリをコピーする。

  • catalina-ant.jar
  • tomcat-util.jar

2. Tomcatのconf/tomcat-users.xmlに以下の記載を追加(ユーザー名、パスワードは任意)

<user username="tomcat" password="tomcat" roles="manager-script" />

3. build.xmlに以下のtaskdefを追加

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project basedir="." default="build" name="ant_project">
<taskdef name="deploy" classname="org.apache.catalina.ant.DeployTask"/>
・
・
・

4. あとはdeployタスクを実行

<deploy url="http://localhost:8080/manager/text"
        username="tomcat"
        password="tomcat"
        path="/${ant.project.name}"
        update="true"
        war="${basedir}/target/${ant.project.name}.war" />

username/passwordはtomcat-users.xmlで指定したもの。

antタスクの依存ライブラリが増えてた。

という感じで。

2017/06/01追記
最初はlocalWarというのが増えたとか書いてたけど、単純にTomcatのバグを踏んでいただけだった・・・・・・
バージョンによっては上の設定だと動かないのでご注意を。
動かない場合は、以下のパッチで直ってますのでantの依存ライブラリだけ入れ替えてあげればおｋ。
https://github.com/apache/tomcat/commit/a64839abf2f4eafb48b738794588a4a99ece0320