Merge pull request #47 from sciencesakura/update_docs

Update documentation
sciencesakura · Jul 7, 2023 · 2a8309c · 2a8309c
2 parents 7fddad5 + e92c160
commit 2a8309c
Show file tree

Hide file tree

Showing 3 changed files with 66 additions and 27 deletions.
diff --git a/README.ja.md b/README.ja.md
@@ -4,7 +4,7 @@
 
 CSV/TSVファイルからデータ取り込みができる[DbSetup](http://dbsetup.ninja-squad.com/)拡張機能です.
 
-![](https://github.com/sciencesakura/dbsetup-csv/workflows/build/badge.svg) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.sciencesakura/dbsetup-csv/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.sciencesakura/dbsetup-csv)
+![](https://github.com/sciencesakura/dbsetup-csv/actions/workflows/check.yaml/badge.svg) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.sciencesakura/dbsetup-csv/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.sciencesakura/dbsetup-csv)
 
 ## Requirements
 
@@ -57,21 +57,31 @@ testImplementation 'com.sciencesakura:dbsetup-csv-kt:2.0.2'
 ```java
 import static com.sciencesakura.dbsetup.csv.Import.csv;
 
-// `testdata.csv`はクラスパス上にある必要があります
-Operation operation = csv("testdata.csv").build();
-DbSetup dbSetup = new DbSetup(destination, operation);
-dbSetup.launch();
+@BeforeEach
+void setUp() {
+    var operations = sequenceOf(
+    truncate("my_table"),
+    // `testdata.csv`はクラスパス上にある必要があります
+    csv("testdata.csv").into("my_table").build());
+    var dbSetup = new DbSetup(destination, operations);
+    dbSetup.launch();
+    }
 ```
 
 ### Kotlin
 
 ```kotlin
 import com.sciencesakura.dbsetup.csv.csv
 
-dbSetup(destination) {
+@BeforeEach
+fun setUp() {
+  dbSetup(destination) {
     // `testdata.csv`はクラスパス上にある必要があります
-    csv("testdata.csv")
-}.launch()
+    csv("testdata.csv") {
+      into("my_table")
+    }
+  }.launch()
+}
 ```
 
 詳細は[APIリファレンス](https://sciencesakura.github.io/dbsetup-csv/)を参照して下さい.

diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 
 A [DbSetup](http://dbsetup.ninja-squad.com/) extension to import data from CSV/TSV files.
 
-![](https://github.com/sciencesakura/dbsetup-csv/workflows/build/badge.svg) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.sciencesakura/dbsetup-csv/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.sciencesakura/dbsetup-csv)
+![](https://github.com/sciencesakura/dbsetup-csv/actions/workflows/check.yaml/badge.svg) [![Maven Central](https://maven-badges.herokuapp.com/maven-central/com.sciencesakura/dbsetup-csv/badge.svg)](https://maven-badges.herokuapp.com/maven-central/com.sciencesakura/dbsetup-csv)
 
 ## Requirements
 
@@ -57,21 +57,31 @@ testImplementation 'com.sciencesakura:dbsetup-csv-kt:2.0.2'
 ```java
 import static com.sciencesakura.dbsetup.csv.Import.csv;
 
-// `testdata.csv` must be in classpath.
-Operation operation = csv("testdata.csv").build();
-DbSetup dbSetup = new DbSetup(destination, operation);
-dbSetup.launch();
+@BeforeEach
+void setUp() {
+  var operations = sequenceOf(
+    truncate("my_table"),
+    // `testdata.csv` must be in classpath.
+    csv("testdata.csv").into("my_table").build());
+  var dbSetup = new DbSetup(destination, operations);
+  dbSetup.launch();
+}
 ```
 
 ### Kotlin
 
 ```kotlin
 import com.sciencesakura.dbsetup.csv.csv
 
-dbSetup(destination) {
+@BeforeEach
+fun setUp() {
+  dbSetup(destination) {
     // `testdata.csv` must be in classpath.
-    csv("testdata.csv")
-}.launch()
+    csv("testdata.csv") {
+      into("my_table")
+    }
+  }.launch()
+}
 ```
 
 See [API reference](https://sciencesakura.github.io/dbsetup-csv/) for details.

diff --git a/core/src/main/java/com/sciencesakura/dbsetup/csv/Import.java b/core/src/main/java/com/sciencesakura/dbsetup/csv/Import.java
@@ -49,17 +49,24 @@
 
 /**
  * An operation which imports the CSV file into the specified table.
- * <p>
- * Usage:
- * </p>
- * <pre><code>
- * import static com.sciencesakura.dbsetup.csv.Import.csv;
  *
- * // `testdata.csv` must be in classpath.
- * Operation operation = csv("testdata.csv").build();
- * DbSetup dbSetup = new DbSetup(destination, operation);
- * dbSetup.launch();
- * </code></pre>
+ * <h2>Usage</h2>
+ * <p>We recommend to import {@code csv} method statically so that your code looks clearer.</p>
+ * <pre>
+ * {@code import static com.sciencesakura.dbsetup.csv.Import.csv;}
+ * </pre>
+ * <p>Then you can use {@code csv} method as follows:</p>
+ * <pre>
+ * {@code @BeforeEach
+ * void setUp() {
+ *   var operations = sequenceOf(
+ *     truncate("my_table"),
+ *     csv("testdata.csv").into("my_table").build());
+ *   var dbSetup = new DbSetup(destination, operations);
+ *   dbSetup.launch();
+ * }
+ * }
+ * </pre>
  *
  * @author sciencesakura
  */
@@ -122,6 +129,17 @@ public void execute(Connection connection, BinderConfiguration configuration) th
     /**
      * A builder to create the {@code Import} instance.
      *
+     * <h2>Usage</h2>
+     * <p>The default settings are:</p>
+     * <ul>
+     *   <li>{@code withCharset("UTF-8")}</li>
+     *   <li>{@code withDelimiter(',')}</li>
+     *   <li>{@code withNullAs("")}</li>
+     *   <li>{@code withQuote('"')}</li>
+     *   <li>The source file name excluding extension is used as the table name.</li>
+     *   <li>The first row of the source file is treated as the header row.</li>
+     * </ul>
+     *
      * @author sciencesakura
      */
     public static final class Builder {
@@ -203,7 +221,8 @@ public Builder withCharset(@NotNull Charset charset) {
          */
         public Builder withCharset(@NotNull String charset) {
             requireNonNull(charset, "charset must not be null");
-            return withCharset(Charset.forName(charset));
+            this.charset = Charset.forName(charset);
+            return this;
         }
 
         /**