Merge pull request #270 from domaframework/translate-and-remove-docs

Translate documents from Japanese into English

Author: nakamura-to

docs/annotation-processing.rst

@@ -1,113 +1,118 @@
-============================
-注釈処理
-============================
+=====================
+Annotation processing
+=====================
 
-.. contents:: 目次
+.. contents::
    :depth: 3
 
-`Pluggable Annotation Processing API <https://www.jcp.org/en/jsr/detail?id=269>`_
-を利用すると、ソースコードの自動生成や検証を **コンパイル時** に行うことができます。
+Doma uses `Pluggable Annotation Processing API <https://www.jcp.org/en/jsr/detail?id=269>`_ at compile time.
 
-DomaではこのAPIを利用することで ``@Entity`` や ``@Dao`` と言ったアノテーションが注釈されたクラスやインタフェースを処理し、
-必要なクラスを自動生成します。
-また、注釈されたクラスやインタフェースの検証を行い、Domaの規約に従っていないソースコードがある場合は
-エラーメッセージをIDE（Eclipseなど）のエディタやjavacを実行したコンソール上に表示します。
+In this document, we describe the options for the annotation processors in Doma
+and show you how to pass them to build tools.
 
-ここでは、Domaが提供するオプションの種類と、ビルドツールごとのオプションの設定方法を説明します。
-
-オプション
-==================
+Options
+=======
 
 doma.dao.package
-  ``@Dao`` が注釈されたインタフェースの実装クラスが生成されるパッケージ。
-  何らかの値を指定した場合、doma.dao.subpackageの指定よりも優先される。
-  デフォルトの値は、 ``@Dao`` が注釈されたインタフェースと同じパッケージ。
+  The package that the generated implementation classes of interfaces annotated with ``@Dao`` belong to.
+  The specified value overrides the value of doma.dao.subpackage.
+  The default value is the same package as the one the interfaces annotated with ``@Dao`` belong to.
 
 doma.dao.subpackage
-  ``@Dao`` が注釈されたインタフェースの実装クラスが生成されるサブパッケージ。
-  doma.dao.packageに値を指定していない場合にのみ有効。
-  ``@Dao`` が注釈されたインタフェースのパッケージが ``example.dao`` で、ここに指定した値が ``impl`` の場合、
-  生成されるクラスのパッケージは ``example.dao.impl`` となる。
+  The subpackage that the generated implementation classes of interfaces annotated with ``@Dao`` belong to.
+  The specified value is overridden by the value of doma.dao.package.
+  If this value is ``impl`` and the package of interfaces annotated with ``@Dao`` is ``example.dao``,
+  the generated implementation classes belong to the package ``example.dao.impl``.
 
 doma.dao.suffix
-  ``@Dao`` が注釈されたインタフェースの実装クラスの名前のサフィックス。
-  ``@Dao`` が注釈されたインタフェースの単純名が ``EmployeeDao`` で、ここに指定した値が ``Bean`` の場合、
-  生成されるクラスの単純名は ``EmployeeDaoBean`` となる。
-  デフォルトの値は ``Impl`` 。
+  The name suffix that the generated implementation classes of interfaces annotated with ``@Dao`` have.
+  If this value is ``Bean`` and the simple name of the interface annotated with ``@Dao`` is ``EmployeeDao``,
+  the simple name of the generated implementation class is ``EmployeeDaoBean``.
+  The default value is ``Impl``.
 
 doma.debug
-  注釈処理のデバッグ情報をログ出力するかどうか。
-  ``true`` の場合、ログ出力を行う。
-  デフォルトの値は、 ``false`` 。
+  Whether to output the debug log in annotation processing.
+  If the value is ``true``, the annotation processors output the debug log.
+  The default value is ``false``.
 
 doma.domain.converters
-  任意の型と基本型を相互変換する ``DomainConverter`` のプロバイダとなるクラスの完全修飾名のカンマ区切り。
-  クラスは ``org.seasar.doma.DomainConverters`` によって注釈されていないければいけない。
+  The full qualified names of the classes annotated with ``@DomainConverters``.
+  The names are described as comma separated list.
+  This value are used to find external domain classes.
 
 doma.entity.field.prefix
-  ``@Entity`` が注釈されたクラスごとに生成されるタイプクラスで使用される。
-  タイプクラスのpublicなフィールド名のプレフィックス。
-  ``none`` を指定するとプレフィックスを使用しないという意味になる。
-  デフォルトの値は、 ``$`` 。
+  The name prefix that the fields of the generated entity meta classes have.
+  The value ``none`` means the prefix is not used.
+  The default value is ``$``.
 
 doma.expr.functions
-  式コメントで利用可能な関数群を表すクラスの完全修飾名。
-  ``org.seasar.doma.expr.ExpressionFunctions`` のサブタイプでなければいけない。
-  デフォルトの値は、 ``org.seasar.doma.expr.ExpressionFunctions`` 。
+  The full qualified name of the class that implements ``org.seasar.doma.expr.ExpressionFunctions``.
+  The default value is ``org.seasar.doma.expr.ExpressionFunctions``.
+  This value are used to determine which functions are available in expression comments.
 
 doma.resources.dir
-  SQLファイルなどリソースファイルの出力先ディレクトリ。
-  絶対パスで指定する。
-  指定しない場合はクラスファイルの出力先ディレクトリが使われる。
+  The resource directory that contains the resource files such as a doma.compile.config file and sql files.
+  Specify the value as an absolute path.
+  If the value is not specified, the resource directory is same as the directory the classes are generated.
 
 doma.sql.validation
-  SQLファイルの存在チェックとSQLコメントの文法チェックを行う場合は ``true`` 。
-  行わない場合は ``false`` 。
-  デフォルトの値は、 ``true`` 。
+  Whether to validate the existence of sql files and the grammar of sql comments.
+  If the value is ``true``, the validations run.
+  To disable the validations, set ``false``.
+  The default value is ``true``.
 
 doma.version.validation
-  注釈処理によるソースコード生成で利用したDomaのバージョンと実行時のDomaのバージョンが同じであることを
-  チェックする場合は ``true`` 。
-  しない場合は ``false`` 。
-  Domaのあるバージョンで生成されたコードを含むライブラリを作成する場合に ``false`` を指定してビルドすると、
-  そのライブラリの再利用性が高まります。
-  ライブラリが依存するDomaのバージョンとは異なるバージョンのDomaで実行できるからです
-  （Domaのバージョンに互換性がある限りにおいて）。
-  デフォルトの値は、 ``true`` 。
+  Whether to validate the versions of doma.jar between runtime and compile-time.
+  If the value is ``true``, the validation runs.
+  To disable the validation, set ``false``.
+  The default value is ``true``.
 
 doma.config.path
-  オプションの設定ファイルを置く場所の指定。
-  デフォルトの値は、 ``doma.compile.config``。
+  The file path of the configuration file for Doma.
+  The default value is ``doma.compile.config``.
 
-Eclipse
-=======
+Setting options in Eclipse
+==========================
 
-プロジェクトの「Properties」-「Java Compiler」-「Annotation Processing」の項目でオプションを登録します。
+- Select “Project > Properties” from the menu bar and open the dialog
+- Select “Java Compiler > Annotation Processing” from the left menu of the dialog
+- Add "Processor options"
 
-IntelliJ IDEA
-=============
+Setting options in IntelliJ IDEA
+================================
 
-Preferrences から Build, Execution, Deployment > Compiler > Annotation Processors の画面を開き登録します。
+- Select "Preferrences" from the menu bar and open the dialog
+- Select "Build, Execution, Deployment > Compiler > Annotation Processors" from the left menu of the dialog
+- Add "Annotation Processor options"
 
-javac
-=====
+Setting options in javac
+========================
 
--Aオプションにより登録します。
-詳細はjavacのドキュメントを参照してください。
+- Use `the -A option <https://docs.oracle.com/javase/8/docs/technotes/tools/windows/javac.html#BHCDIFEE>`_
 
-Gradle
-======
+Setting options in Gradle
+=========================
 
-``compileJava.options.compilerArgs`` に指定します。
+- Use `the compilerArgs property
+  <https://docs.gradle.org/5.0/dsl/org.gradle.api.tasks.compile.CompileOptions.html#org.gradle.api.tasks.compile.CompileOptions:compilerArgs>`_
 
 .. code-block:: groovy
 
-  compileJava.options.compilerArgs = ['-Adoma.dao.subpackage=impl', '-Adoma.dao.suffix=Impl']
+  compileJava {
+      options {
+          compilerArgs = ['-Adoma.dao.subpackage=impl', '-Adoma.dao.suffix=Impl']
+      }
+  }
+
+Setting options with configuration file
+=======================================
+
+The options specified in the ``doma.compile.config`` file are available in all build tools
+such as Eclipse, IDEA, Gradle and so on.
 
-設定ファイル
-==================
+The ``doma.compile.config`` file must follow the properties file format
+and be placed in the root directory such as ``src/main/resources``.
 
-デフォルトでは ``main/resources/doma.compile.config`` ファイルにオプションを記述しておくことで、
-ビルドツールごとのオプションの設定を利用する必要がなくなります。
-記述形式はプロパティファイルと同様です。
-なお、設定がバッティングした場合、ビルドツールごとのオプションの設定が優先されます。
+.. note::
+  The options specified in the ``doma.compile.config`` file are overridden by
+  the ones specific to the build tools.

docs/build.rst

@@ -1,91 +1,77 @@
-==================
-ビルド
-==================
+=======================
+Building an application
+=======================
 
-.. contents:: 目次
+.. contents::
    :depth: 3
 
+Before You Start
+================
+
 Maven Central Repository
-========================
+------------------------
 
-Doma の jar ファイルは Maven Central Repository から入手できます。
-GroupId と ArtifactId の名称は以下の通りです。
+You can pull the jar file of the Doma framework from the Maven central repository.
+The group id and artifact id are as follows:
 
 :GroupId: org.seasar.doma
 :ArtifactId: doma
 
-.. _eclipse-build:
-
-Eclipse を使ったビルド
-======================
+See also: https://search.maven.org/artifact/org.seasar.doma/doma/
 
-Eclipse でビルドを行う際のポイントは以下の通りです。
+.. _eclipse-build:
 
-* プロジェクトの設定で注釈処理を有効にする
-* Build Path に加えて Factory Path にも Doma の jar ファイルを設定する
+Build with Eclipse
+==================
 
 .. note::
 
-  手動で設定するよりも Gradle の eclipse タスクで自動設定することを推奨します。
-  詳細については、
-  `domaframework/simple-boilerplate <https://github.com/domaframework/simple-boilerplate>`_ 
-  に含まれる build.gradle と eclipse.gradle を参照ください。
+  Instead of manual settings we show you below,
+  we recommend to generate eclipse setting files automatically with
+  `the Gradle Eclipse Plugin <https://docs.gradle.org/current/userguide/eclipse_plugin.html>`_.
+  See also build.gradle and eclipse.gradle in the
+  `domaframework/simple-boilerplate <https://github.com/domaframework/simple-boilerplate>`_
+  repository.
 
-注釈処理の有効化
-----------------
+Enabling annotation processing
+------------------------------
 
-注釈処理を有効化するには、メニューから Project > Properties を選んで画面を開き
-左のメユーから Java Compiler > Annotation Processing を選択します。
-
-そして、下記に示すチェックボックスにチェックを入れます。
+- Select "Project > Properties" from the menu bar and open the dialog
+- Select "Java Compiler > Annotation Processing" from the left menu of the dialog
+- Check as follows:
 
 .. image:: images/annotation-processing.png
    :width: 80 %
 
-|
-
-Factory Path の設定
--------------------
+Setting factory path
+--------------------
 
-注釈処理を有効化するには、メニューから Project > Properties を選んで画面を開き
-左のメユーから Java Compiler > Annotation Processing > Factory Path を選択します。
-
-そして、下記に示すチェックボックスにチェックを入れ、
-ビルドパスで指定しているのと同じバージョンの Doma の jar を登録します。
+- Select "Project > Properties" from the menu bar and open the dialog
+- Select "Java Compiler > Annotation Processing > Factory Path" from the left menu of the dialog
+- Add the jar file of the Doma framework whose version is same as the one in the Java Build Path
+- Check as follows:
 
 .. image:: images/factory-path.png
    :width: 80 %
 
-|
-
-IntelliJ IDEA を使ったビルド
-================================
-
-IntelliJ IDEA でビルドを行う際のポイントは以下の通りです。
-
-* Module の設定で Inherit project compile output pathを有効にする
-* Preferences の設定で注釈処理を有効にする
-* 注釈処理で生成されたコードが出力されるディレクトリを Generated Sources Root に設定する
-
-詳細な設定方法については :ref:`idea-annotation-processor` を参照してください。
+Build with IntelliJ IDEA
+========================
 
-Gradle を使ったビルド
-=====================
+See :ref:`idea-annotation-processor`.
 
-Gradle でビルドを行う際のポイントは以下のとおりです。
+.. _build-with-gradle:
 
-* compileJava実行前にdomaが注釈処理で参照するリソースをcompileJavaタスクの出力先ディレクトリにコピーする
-* テスト時は注釈処理を無効にする
-* 依存関係の設定でdomaの注釈処理を実行することを示す
-* 依存関係の設定でdomaへの依存を示す
+Build with Gradle
+=================
 
-サンプルのbuild.gradleです。
+build.gradle as an example:
 
 .. code-block:: groovy
 
   apply plugin: 'java'
 
-  // domaが注釈処理で参照するリソースをcompileJavaタスクの出力先ディレクトリにコピーする
+  // Copy the resources referred by the Doma annotation processors to
+  // the destinationDir of the compileJava task
   task copyDomaResources(type: Sync)  {
       from sourceSets.main.resources.srcDirs
       into compileJava.destinationDir
@@ -94,22 +80,20 @@ Gradle でビルドを行う際のポイントは以下のとおりです。
       include 'META-INF/**/*.script'
   }
 
- 　compileJava {
-   　　 // 上述のタスクに依存させる
-  　　  dependsOn copyDomaResources
-    　　options.encoding = 'UTF-8'
- 　}
+  compileJava {
+      // Depend on the above task
+      dependsOn copyDomaResources
+      options.encoding = 'UTF-8'
+  }
 
   compileTestJava {
       options.encoding = 'UTF-8'
-      // テストの実行時は注釈処理を無効にする
+      // Disable the annotation processors during the test run
       options.compilerArgs = ['-proc:none']
   }
 
   dependencies {
-      // domaの注釈処理を実行することを示す
       annotationProcessor "org.seasar.doma:doma:2.21.1-SNAPSHOT"
-      // domaへの依存を示す
       implementation "org.seasar.doma:doma:2.21.1-SNAPSHOT"
   }
 
@@ -120,18 +104,13 @@ Gradle でビルドを行う際のポイントは以下のとおりです。
 
 .. note::
 
-  リポジトリにおける https://oss.sonatype.org/content/repositories/snapshots/ の設定は
-  Doma の SNAPSHOT を参照したい場合にのみ必要です。
-
-  Doma の SNAPSHOT は `Travis-CI <https://travis-ci.org/domaframework/doma>`_
-  でビルドが成功されるたびに作成されリポジトリに配置されます。
+  The description ``maven {url 'https://oss.sonatype.org/content/repositories/snapshots/'}`` is required
+  only when you need the SNAPSHOT version of the Doma framework.
 
 .. note::
 
-  上述のbuild.gradleの書き方により、Gradle 5.0 で導入された
-  `Incremental annotation processing <https://gradle.org/whats-new/gradle-5/#incremental-annotation-processing>`_ の恩恵を受けられます。
-  
+  With the above build.gradle, you will benefits from
+  `Incremental annotation processing <https://gradle.org/whats-new/gradle-5/#incremental-annotation-processing>`_.
 
-Gradle を使ったより詳細なビルドスクリプトの例として、
-`domaframework/simple-boilerplate <https://github.com/domaframework/simple-boilerplate>`_ 
-を参照にしてください。
+See also build.gradle in the
+`domaframework/simple-boilerplate <https://github.com/domaframework/simple-boilerplate>`_ repository.