Merge pull request #290 from domaframework/translate

Polish documents

Author: nakamura-to

docs/faq.rst

@@ -5,8 +5,8 @@ Frequently Asked Questions
 .. contents::
    :depth: 3
 
-General Questions
-=================
+General
+=======
 
 What does "Doma" mean?
 ----------------------
@@ -19,11 +19,11 @@ What is annotation processing?
 Annotation processing, that was introduced in Java 6,
 allows us to validate and generate source code at compile time.
 
-We use annotation processing to the following:
+We use annotation processing for the following purposes:
 
-- generating meta classes from the classes annotated with ``@Entity`` and ``@Domain``;
-- generating implementation classes of the interfaces annotated with ``@Dao``; and
-- validating SQL statements.
+- Generating meta classes from the classes annotated with ``@Entity`` and ``@Domain``.
+- Generating implementation classes of the interfaces annotated with ``@Dao``.
+- Validating SQL templates.
 
 Runtime environment
 ===================
@@ -93,11 +93,11 @@ Does Doma generate SQL statements?
 
 Yes, Doma generates the following statements:
 
-- INSERT;
-- DELETE;
-- UPDATE;
-- stored procedure call; and
-- stored function call.
+- INSERT
+- DELETE
+- UPDATE
+- Stored procedure call
+- Stored function call
 
 Doma doesn't generate SELECT statements
 but executes arbitrary SELECT statements and maps the results to the Java objects.

docs/index.rst

@@ -18,7 +18,8 @@ Doma has various strengths:
 * Verifies and generates source code at compile time using annotation processing.
 * Maps database columns to user-defined Java objects.
 * Uses SQL templates, called "two-way SQL".
-* Supports classes introduced in Java 8, such as ``java.time.LocalDate``, ``java.util.Optional``, and ``java.util.stream.Stream``.
+* Supports classes introduced in Java 8, such as ``java.time.LocalDate``,
+  ``java.util.Optional``, and ``java.util.stream.Stream``.
 * Has no dependence on other libraries.
 
 This document consists of following sections:
@@ -28,6 +29,14 @@ This document consists of following sections:
 * `About Doma`_
 * `Links`_
 
+.. admonition:: Help improve our documentation
+  :class: important
+
+  Have feedback or a question? Found a typo?
+
+  Please add an issue or pull request to
+  https://github.com/domaframework/doma and we’ll get back to you.
+
 User Documentation
 ==================
 
@@ -72,6 +81,7 @@ About Doma
 Links
 =====
 
+* `News and announcements <https://twitter.com/domaframework>`_
 * `GitHub repository <https://github.com/domaframework/doma>`_
 * `JavaDoc <http://www.javadoc.io/doc/org.seasar.doma/doma>`_
 * `Examples <https://github.com/domaframework/simple-examples>`_

docs/kotlin-support.rst

@@ -130,9 +130,9 @@ If you use resource files such as SQL files, make the kapt find them:
 
     Remember that you always have options as follows:
 
-    - Write all codes with Kotlin
-    - Write all codes with Java
-    - Write codes annotated with Doma's annotations in Java and others in Kotlin
+    - Write all code in Kotlin
+    - Write all code in Java
+    - Write code 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.
 

docs/lombok-support.rst

@@ -14,15 +14,15 @@ Doma supports `Lombok <https://projectlombok.org/>`_ 1.16.12 or above.
 Overview
 ========
 
-Both Lombok and Doma provide their own annotation processors.
+Both Lombok and Doma provide 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.
+Doma's annotation processors are not always aware of the class modifications made by
+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.
+To resolve the issue, Doma's annotation processors recognize several of Lombok's annotations
+and change their behavior.
+For example, if Doma's annotation processors find a class annotated with ``@lombok.Value``,
+they suppose that the class has a constructor whose arguments cover all instance fields.
 
 Best practices
 ==============

docs/sql.rst

@@ -11,8 +11,8 @@ Overview
 Doma supports SQL templates, called "two-way SQL".
 "Two-way SQL" means that the SQL templates can be used in two ways:
 
-1. to build dynamic SQL statements from the templates; and
-2. to execute the templates in SQL tools as they are.
+* To build dynamic SQL statements from the templates.
+* To execute the templates in SQL tools as they are.
 
 Every SQL template must correspond to a DAO method.
 For example, suppose you have the pair of an SQL template and a DAO method as follows: