Merge pull request #262 from domaframework/translate-javadoc-comments

Translate javadoc comments from Japanese to English

Author: nakamura-to

src/main/java/org/seasar/doma/AccessLevel.java

@@ -1,26 +1,6 @@
-/*
- * Copyright 2004-2010 the Seasar Foundation and the Others.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
- * either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
 package org.seasar.doma;
 
-/**
- * Javaのアクセスレベルを表します。
- *
- * @author nakamura-to
- * @since 2.0.0
- */
+/** Defines access levels in The Java Language. */
 public enum AccessLevel {
 
   /** {@code public} */
@@ -29,20 +9,16 @@ public enum AccessLevel {
   /** {@code protected} */
   PROTECTED("protected"),
 
-  /** パッケージプライベート */
+  /** package private */
   PACKAGE("");
 
   private final String modifier;
 
-  private AccessLevel(String modifier) {
+  AccessLevel(String modifier) {
     this.modifier = modifier;
   }
 
-  /**
-   * 修飾子を返します。
-   *
-   * @return 修飾子
-   */
+  /** @return the modifier's name */
   public String getModifier() {
     return modifier;
   }

src/main/java/org/seasar/doma/AnnotateWith.java

@@ -1,48 +1,59 @@
-/*
- * Copyright 2004-2010 the Seasar Foundation and the Others.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
- * either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
 package org.seasar.doma;
 
 import java.lang.annotation.ElementType;
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
+import org.seasar.doma.jdbc.Config;
 
 /**
- * Daoインタフェースの実装クラスのソースコードにアノテーションを注釈することを示します。
+ * Indicates that a generated code that implements the annotated interface is annotated with some
+ * annotations.
  *
- * <p>このアノテーションには2種類の使い方があります
+ * <p>This annotation is mainly intended to inject a {@link Config} instance to a DAO
+ * implementation's constructor. Don't use {@link Dao#config()} with this annotation.
+ *
+ * <p>There are 2 ways to use this annotation:
  *
  * <ul>
- *   <li>Daoインタフェースに直接的に注釈する方法。
- *   <li>Daoインタフェースに間接的に注釈する方法。この方法では、任意のアノテーションに{@code AnnotateWith}
- *       を注釈し、そのアノテーションをDaoインタフェースに注釈する。
+ *   <li>annotate directly
+ *   <li>annotate indirectly
  * </ul>
  *
- * <p>このアノテーションを直接的であれ間接的であれDaoインタフェースに注釈する場合、{@link Dao#config()} に値を設定してはいけません。
+ * <p>annotate directly:
+ *
+ * <pre>
+ * &#64;Dao
+ * &#64;AnnotateWith(annotations = {
+ *   &#64;Annotation(target = AnnotationTarget.CONSTRUCTOR, type = javax.inject.Inject.class),
+ *   &#64;Annotation(target = AnnotationTarget.CONSTRUCTOR_PARAMETER, type = javax.inject.Named.class, elements = "\"config\"") })
+ * public interface EmployeeDao {
+ *    ...
+ * }
+ * </pre>
+ *
+ * annotate indirectly:
+ *
+ * <pre>
+ * &#64;AnnotateWith(annotations = {
+ *         &#64;Annotation(target = AnnotationTarget.CONSTRUCTOR, type = javax.inject.Inject.class),
+ *         &#64;Annotation(target = AnnotationTarget.CONSTRUCTOR_PARAMETER, type = javax.inject.Named.class, elements = "\"config\"") })
+ * public @interface InjectConfig {
+ * }
+ * </pre>
  *
- * @author taedium
+ * <pre>
+ * &#64;Dao
+ * &#64;InjectConfig
+ * public interface EmployeeDao {
+ *    ...
+ * }
+ * </pre>
  */
 @Target({ElementType.TYPE, ElementType.ANNOTATION_TYPE})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface AnnotateWith {
 
-  /**
-   * アノテーションの配列を返します。
-   *
-   * @return アノテーションの配列
-   */
+  /** @return the {@link Annotation} array. */
   Annotation[] annotations();
 }

src/main/java/org/seasar/doma/Annotation.java

@@ -1,52 +1,31 @@
-/*
- * Copyright 2004-2010 the Seasar Foundation and the Others.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
- * either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
 package org.seasar.doma;
 
 import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 
 /**
- * アノテーションを示します。
- *
- * @author taedium
- * @see AnnotateWith
+ * Used in conjunction with the {@link AnnotateWith} annotation to indicate which kind of annotation
+ * is specified for generated code.
  */
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Annotation {
 
-  /**
-   * 注釈する対象を返します。
-   *
-   * @return 注釈する対象
-   */
+  /** @return the location where the annotation is specified. */
   AnnotationTarget target();
 
-  /**
-   * アノテーションの型を返します。
-   *
-   * @return アノテーションの型
-   */
+  /** @return the annotation class that this annotation represents. */
   Class<? extends java.lang.annotation.Annotation> type();
 
   /**
-   * アノテーションの要素を返します。
+   * The annotation elements as a set of key-value pair.
+   *
+   * <p>Represented in CSV format:
    *
-   * <p>「要素名 = 値」 形式で文字列を記述します。 複数存在する場合はカンマで区切ります。
+   * <pre>
+   * elementName1=value1, elementName2=value2
+   * </pre>
    *
-   * @return アノテーションの要素
+   * @return the annotation elements
    */
   String elements() default "";
 }

src/main/java/org/seasar/doma/AnnotationTarget.java

@@ -1,34 +1,18 @@
-/*
- * Copyright 2004-2010 the Seasar Foundation and the Others.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
- * either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
 package org.seasar.doma;
 
 /**
- * アノテーションを注釈する対象です。
+ * Defines the locations where annotations may appear.
  *
- * @author taedium
  * @see Annotation
  */
 public enum AnnotationTarget {
 
-  /** クラス */
+  /** Class */
   CLASS,
 
-  /** コンストラクタ */
+  /** Constructor */
   CONSTRUCTOR,
 
-  /** コンストラクターのパラメータ */
+  /** Constructor's parameter */
   CONSTRUCTOR_PARAMETER,
 }

src/main/java/org/seasar/doma/ArrayFactory.java

@@ -1,18 +1,3 @@
-/*
- * Copyright 2004-2010 the Seasar Foundation and the Others.
- *
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- *
- *     http://www.apache.org/licenses/LICENSE-2.0
- *
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
- * either express or implied. See the License for the specific language
- * governing permissions and limitations under the License.
- */
 package org.seasar.doma;
 
 import java.lang.annotation.ElementType;
@@ -24,11 +9,9 @@
 import org.seasar.doma.jdbc.JdbcException;
 
 /**
- * {@link Array} のインスタンスを生成することを示します。
- *
- * <p>このアノテーションが注釈されるメソッドは、 Daoインタフェースのメンバでなければいけません。
+ * Indicates to create an {@link Array} instance.
  *
- * <h3>例:</h3>
+ * <p>The annotated method must be a member of a {@link Dao} annotated interface.
  *
  * <pre>
  * &#064;Dao(config = AppConfig.class)
@@ -39,14 +22,13 @@
  * }
  * </pre>
  *
- * 注釈されるメソッドは、次の例外をスローすることがあります。
+ * The method may throw following exceptions:
  *
  * <ul>
- *   <li>{@link DomaNullPointerException} パラメータに {@code null}を渡した場合
- *   <li>{@link JdbcException} JDBCに関する例外が発生した場合
+ *   <li>{@link DomaNullPointerException} if any of the method parameters are {@code null}
+ *   <li>{@link JdbcException} if a JDBC related error occurs
  * </ul>
  *
- * @author taedium
  * @see Connection#createArrayOf(String, Object[])
  */
 @Target(ElementType.METHOD)
@@ -55,11 +37,12 @@
 public @interface ArrayFactory {
 
   /**
-   * 配列の要素がマッピングされる型のSQL名を返します。。
+   * The SQL name of the type the elements of the array map to.
    *
-   * <p>この値は、 {@link Connection#createArrayOf(String, Object[])} の最初のパラメータに渡されます。
+   * <p>The value is passed as the first argument to {@link Connection#createArrayOf(String,
+   * Object[])}.
    *
-   * @return 配列の要素がマッピングされる型のSQL名
+   * @return the type name
    */
   String typeName();
 }