Merge pull request #273 from domaframework/translate

Translate lombok-support.rst and kotlin-support.rst from Japanese into English

Author: nakamura-to

docs/kotlin-support.rst

@@ -1,124 +1,142 @@
-==================
-Kotlin サポート
-==================
+==============
+Kotlin support
+==============
 
-.. contents:: 目次
+.. contents::
    :depth: 3
 
-Doma は `Kotlin <https://kotlinlang.org/>`_ 1.1.2を実験的にサポートしています。
+Doma supports `Kotlin <https://kotlinlang.org/>`_ 1.3.11 or above **experimentally**.
 
-Kotlin利用のベストプラクティス
-================================
+Best practices
+==============
 
-クラスの定義やビルドに関する事柄について推奨する方法を記載します。
+We show you recommended ways to define classes and build them with Kotlin.
 
-エンティティクラス
--------------------
+Entity classes
+--------------
 
-* Data Classで定義する
-* イミュータブルで定義する（ `@Entity` の `immutable` 要素に `true` を設定する）
-* コンストラクタは1つだけ定義する
-* コンストラクタ以外でプロパティを定義しない
-* コンストラクタで定義するプロパティには `val` を使用する
+* Define as a data class
+* Specify ``true`` to the ``immutable`` element of ``@Entity``
+* Define only one constructor
+* Define properties only in the constructor
+* Use `val` for the property definitions
 
 .. code-block:: java
 
   @Entity(immutable = true)
   data class Person(
         @Id
-        @GeneratedValue(strategy = org.seasar.doma.GenerationType.IDENTITY)
+        @GeneratedValue(strategy = GenerationType.IDENTITY)
         val id: Int? = null,
         val name: Name,
         val address: Address)
 
-ドメインクラス
--------------------
+Domain classes
+--------------
 
-* Data Classで定義する
-* コンストラクタは1つだけ定義する
-* コンストラクタで定義するプロパティの名前は `value` にする
-* コンストラクタで定義するプロパティには `val` を使用する
+* Define as a data class
+* Define only one constructor
+* Define only one property whose name is ``value`` in the constructor
+* Use `val` for the property definition
 
 .. code-block:: java
 
   @Domain(valueType = String::class)
   data class Name(val value: String)
 
-エンベッダブルクラス
-----------------------
+Embeddable classes
+------------------
 
-* Data Classで定義する
-* コンストラクタは1つだけ定義する
-* コンストラクタ以外でプロパティを定義しない
-* コンストラクタで定義するプロパティには `val` を使用する
+* Define as a data class
+* Define only one constructor
+* Define properties only in the constructor
+* Use `val` for the property definitions
 
 .. code-block:: java
 
   @Embeddable
   data class Address(val city: String, val street: String)
 
-Daoインタフェース
--------------------
+Dao interfaces
+--------------
 
-* KotlinではなくJavaで定義する
-* 更新処理の戻り値の型は `org.seasar.doma.jdbc.Result` や `org.seasar.doma.jdbc.BatchResult` を使う
+* Specify a SQL template to ``@org.seasar.doma.experimental.Sql``
+* Use ``org.seasar.doma.jdbc.Result`` as the return type of ``@Delete``, ``@Insert`` and ``@Update``
+* Use ``org.seasar.doma.jdbc.BatchResult`` as the return type of
+  ``@BatchDelete``, ``@BatchInsert`` and ``@BatchUpdate``
 
 .. code-block:: java
 
-  @Dao(config = AppConfig.class)
-  public interface PersonDao {
+  @Dao(config = AppConfig::class)
+  interface PersonDao {
+    @Sql("""
+    select * from person where id = /*id*/0
+    """)
     @Select
-    Person selectById(Integer id);
+    fun selectById(id: Int): Person
+
     @Insert
     Result<Person> insert(Person person);
   }
 
-* 更新処理の戻り値を扱う際は `Destructuring Declarations <https://kotlinlang.org/docs/reference/multi-declarations.html>`_ を使う
+* Use `Destructuring Declarations <https://kotlinlang.org/docs/reference/multi-declarations.html>`_
+  for ``org.seasar.doma.jdbc.Result`` and ``org.seasar.doma.jdbc.BatchResult``
 
 .. code-block:: java
 
   val dao: PersonDao = ...
   val person = Person(name = Name("Jhon"), address = Address(city = "Tokyo", street = "Yaesu"))
   val (newPerson, count) = dao.insert(person)
 
+Using kapt in Gradle
+--------------------
 
-kaptによるビルド
--------------------
-
-Kotlinで記述されたクラスやインタフェースに対して注釈処理をするには `kapt <https://blog.jetbrains.com/kotlin/2016/12/kotlin-1-0-6-is-here/>`_ を実行する必要があります。
-kaptは実験的な位置付けにありドキュメントがありません。
-Gradleでビルドする際は、確実な注釈処理が行われるように常に `clean build` を実行することを推奨します。
+Annotation processors are supported in Kotlin with the
+`kapt <https://kotlinlang.org/docs/reference/kapt.html>`_ compiler plugin.
 
-.. code-block:: sh
+Add the dependencies using the `kapt` and `implementation` configuration in your dependencies block:
 
-  ./gradlew clean build
+.. code-block:: groovy
 
-Eclispeを利用する場合設定を適切に行えばJavaの注釈処理は自動で行われますが、kapt（Kotlinの注釈処理）はGradleを実行しない限り行われないことに注意してください。
+  dependencies {
+      kapt "org.seasar.doma:doma:2.21.1-SNAPSHOT"
+      implementation "org.seasar.doma:doma:2.21.1-SNAPSHOT"
+  }
 
-下記はbuild.gradleの抜粋です。コンパイル時にSQLファイルを参照するために下記の設定に特に注意してください。
+If you use resource files such as SQL files, make the kapt find them:
 
 .. code-block:: groovy
 
-  // コンパイルより前にSQLファイルを出力先ディレクトリにコピーするために依存関係を逆転する
-  compileJava.dependsOn processResources
-  
-  // SQLファイルなどリソースファイルの出力先ディレクトリをkaptに伝える
-  kapt {
-      arguments {
-          arg("doma.resources.dir", processResources.destinationDir)
-      }
-  }
+    kapt {
+        arguments {
+            arg("doma.resources.dir", compileKotlin.destinationDir)
+        }
+    }
+
+    task copyDomaResources(type: Sync)  {
+        from sourceSets.main.resources.srcDirs
+        into compileKotlin.destinationDir
+        include 'doma.compile.config'
+        include 'META-INF/**/*.sql'
+        include 'META-INF/**/*.script'
+    }
+
+    compileKotlin {
+        dependsOn copyDomaResources
+    }
+
 
+.. note::
 
-JavaとKotlinの混在
--------------------------
+    Remember that you always have options as follows:
 
-kaptの不確実な挙動を避けるため、Domaに関するコードの全てをJavaで書くことは検討に値します。
-Domaの利用において、JavaとKotlinの混在は問題ありません。
+    - Write all codes with Kotlin
+    - Write all codes with Java
+    - Write codes annotated with Doma's annotations in Java and others in Kotlin
 
-サンプルプロジェクト
-=====================
+    The third option is worth considering, because it can avoid some troubles with the kapt.
 
-サンプルコードについては下記のプロジェクトを参照ください。
+Sample project
+==============
 
 * `kotlin-sample <https://github.com/domaframework/kotlin-sample>`_

docs/lombok-support.rst

@@ -1,51 +1,43 @@
-==================
-Lombok サポート
-==================
+==============
+Lombok support
+==============
 
-.. contents:: 目次
+.. contents::
    :depth: 3
 
-Doma は `Lombok <https://projectlombok.org/>`_ のバージョン 1.16.12 以上をサポートしています。
+Doma supports `Lombok <https://projectlombok.org/>`_ 1.16.12 or above.
 
 .. note::
 
-  IDE として Eclipse を利用する場合はバージョン 4.5 以上を使ってください。
-  4.5 未満ではアノテーションプロッサで取得されるクラスに定義されたフィールドなどの並びがソースコードに記載されている順序と異なり、
-  正しく動作しないためです。
+  If you intend to use Eclipse, use version 4.5 or above.
 
-Lombok サポートの概要
-================================
+Overview
+========
 
-Lombok と Doma は共に JSR 269 で規定されたアノテーションプロセッサを提供していますが、
-Lombok と Doma を同時に利用する場合はアノテーションプロセッサの処理順序が問題になることがあります。
-例えば、 Lombok のアノテーションプロセッサがコンストラクタを生成し、
-Doma のアノテーションプロセッサがそのコンストラクタを読み取る場合などです。
-仮に、Doma のアノテーションプロセッサが先に実行されると単にコンストラクタが定義されていないものとして動作し、
-コンパイルに失敗します。
+Both Lombok and Doma provide their own annotation processors.
+Because the execution order of annotation processors is not determined in Java,
+the Doma's annotation processors are not always aware of the class modifications made by
+the Lombok annotation processors.
 
-アノテーションプロセッサの処理順序を指定できればこの問題は解決するのですが、
-残念ながら処理順序が保証されないことが仕様に記載されており、実際に問題解決の仕組みは提供されていません。
+To resolve the issue, the Doma's annotation processors recognise several Lombok's annotations
+and change their own behavior.
+For example, if the Doma's annotation processors find a class annotated with ``@lombok.Value``,
+they supposes that the class has a constructor whose arguments covers all instance fields.
 
-Doma では、この問題に対応するために、Lombok のアノテーションの有無を認識して処理順序に依存にしない振る舞いをするようにしています。
-先ほどの例で言えば、 ``@lombok.Value`` などコンストラクタを生成するLombokのアノテーションが存在する場合は
-実際にはコンストラクタを読み取らなくてもコンストラクタが存在するものとして動作するということです。
+Best practices
+==============
 
-Lombok 利用のベストプラクティス
-================================
+We show you recommended ways to define classes with Lombok annotations.
 
-Lombok のアノテーションを用いたクラスの定義について推奨する方法を記載します。
+Entity class definition
+-----------------------
 
-エンティティクラス
--------------------
+immutable entity classes
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-immutable（イミュータブル）
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-イミュータブルなエンティティクラスを定義する場合は下記の点に注意します。
-
-* ``@Entity`` の ``immutable`` 要素に ``true`` を設定する
-* ``@lombok.Value`` もしくは ``@lombok.AllArgsConstructor`` を注釈する
-* ``@lombok.AllArgsConstructor`` を選んだ場合、getterを生成するためには ``@lombok.Getter`` を注釈する
+* Specify ``true`` to the ``immutable`` element of ``@Entity``
+* Specify either ``@lombok.Value`` or ``@lombok.AllArgsConstructor``
+* Specify ``@lombok.Getter`` to generate getters, in case of ``@lombok.AllArgsConstructor``
 
 .. code-block:: java
 
@@ -70,13 +62,11 @@ immutable（イミュータブル）
     private final Age age;
   }
 
-mutable（ミュータブル）
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-ミュータブルなエンティティクラスを定義する場合は下記の点に注意します。
+mutable entity classes
+~~~~~~~~~~~~~~~~~~~~~~
 
-* デフォルトコンストラクタを定義する（デフォルトコンストラクタの生成を抑制しない）
-* getter/setterを生成する場合は ``@lombok.Data`` もしくは ``@lombok.Getter`` / ``@lombok.Setter`` を注釈する
+* Define a default constructor
+* Specify ``@lombok.Data`` or ``@lombok.Getter``/``@lombok.Setter`` to generate getters/setters
 
 .. code-block:: java
 
@@ -101,13 +91,11 @@ mutable（ミュータブル）
     private Age age;
   }
 
-ドメインクラス
--------------------
+Domain class definition
+-----------------------
 
-ドメインクラスを定義する場合は下記の点に注意します。
-
-* ``@lombok.Value`` を注釈する
-* インスタンスフィールドは1つだけ定義し名前は ``value`` にする
+* Specify ``@lombok.Value``
+* Define only one instance field whose name is ``value``
 
 .. code-block:: java
 
@@ -117,13 +105,11 @@ mutable（ミュータブル）
     Integer value;
   }
 
-エンベッダブルクラス
-----------------------
-
-エンベッダブルクラスを定義する場合は下記の点に注意します。
+Embeddable class definition
+---------------------------
 
-* ``@lombok.Value`` もしくは ``@lombok.AllArgsConstructor`` を注釈する
-* ``@lombok.AllArgsConstructor`` を選んだ場合、getterを生成するためには ``@lombok.Getter`` を注釈する
+* Specify either ``@lombok.Value`` or ``@lombok.AllArgsConstructor``
+* Specify ``@lombok.Getter`` to generate getters, in case of ``@lombok.AllArgsConstructor``
 
 .. code-block:: java