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/
persistence unitを日本語に翻訳するときどちらにしますか?
— m6s (@megascus) 2018年1月3日
tableの翻訳結果はどちらのほうがよいでしょうか?
— m6s (@megascus) 2018年1月19日
columnの翻訳結果はどちらのほうがよいでしょうか?
— m6s (@megascus) 2018年1月19日
relationshipの翻訳結果はどちらがよいでしょう?
— m6s (@megascus) 2018年1月19日
primary keyの翻訳はどちらがよいでしょうか?
— m6s (@megascus) 2018年1月19日
foreign keyの翻訳はどれがよいでしょうか?
— m6s (@megascus) 2018年1月19日
さて、やはりJPAのjavadocではrelationという単語は使われてないな。relationshipだけだ。
— m6s (@megascus) 2018年1月20日
関係データモデルにおいてrelation(関係)とは属性とその属性に対するタプルの集合を指すので、つまりテーブルのことです。PostgreSQLなんかはテーブルのことをrelationと呼んでいますね。なのでrelationという言葉は一切出てこないはずです。
— AOE Takashi (@aoetk) 2018年1月20日
日本語での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を翻訳しての感想)
ですます調で書きましょう。
ドキュメントは誰かに読んでもらうものです。
できる限り丁寧な言葉づかいで書いたほうが喜ばれます。
断定調だと高圧的な感じになってしまいますし、なんかさー、とか、適当な口語をつかわれると読んでてだるいと感じるわけよ。
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も日本語化されるだけでも非常に有用だと思うのですが。
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ブランチを作成していない場合、公開対象として表示されないので注意