[Java] Update docs around data tables

Author: mpkorstanje

java/README.md

@@ -93,13 +93,16 @@ public class Steps {
 
 ### Data Table Type
 
-Data table types can be declared by annotating a method with `@DataTableType`. Depending on the parameter type this
-will be either a: 
+Data table types can be declared by annotating a method with `@DataTableType`. 
+Depending on the parameter type this will be either a: 
  * `String` -> `io.cucumber.datatable.TableCellTranformer`
- * `Map<String,String>` -> `io.cucumber.datatable.TableEntry`
- * `List<String` -> `io.cucumber.datatable.TableRow`
+ * `Map<String,String>` -> `io.cucumber.datatable.TableEntryTransformer`
+ * `List<String` -> `io.cucumber.datatable.TableRowTranformer`
  * `DataTable` -> `io.cucumber.datatable.TableTransformer`
 
+For a full list of transformations that can be achieved with data table types
+see [cucumber/datatable](https://github.com/cucumber/cucumber/tree/master/datatable)
+
 ```java
 package com.example.app;
 
@@ -204,3 +207,47 @@ public class DataTableSteps {
     }
 }
 ```
+
+# Transposing Tables
+
+A data table can be transposed by annotating the data table parameter (or the
+parameter the data table will be converted into) with `@Transpose`. This means
+the keys will be in the first column rather then the first row.
+
+
+```gherkin
+ Given the user is
+    | firstname	    | Roberto	|
+    | lastname	    | Lo Giacco |
+    | nationality	| Italian	|
+ ```
+
+And a data table type to create a User
+
+```java 
+package com.example.app;
+
+import io.cucumber.java.DataTableType;
+import io.cucumber.java.en.Given;
+import io.cucumber.java.Transpose;
+
+import java.util.Map;
+import java.util.List;
+
+public class DataTableSteps {
+
+    @DataTableType
+    public User convert(Map<String, String> entry){
+      return new User(
+         entry.get("firstname"),
+         entry.get("lastname")
+         entry.get("nationality")
+      );
+    }
+    
+    @Given("the user is")
+    public void the_user_is(@Transpose User user){
+      // user  = [User(firstname="Roberto", lastname="Lo Giacco", nationality="Italian")
+    }
+}
+```

java/src/main/java/io/cucumber/java/Transpose.java

@@ -23,18 +23,16 @@
  * And a data table type to create a User
  *
  * <pre>
- * typeRegistry.defineDataTableType(new DataTableType(
- *    Author.class,
- *    new TableEntryTransformer&lt;User&gt;() {
- *    &#064;Override
- *    public Author transform(Map&lt;String, String&gt; entry) {
- *       return new User(
- *          entry.get("firstName"),
- *          entry.get("lastName"),
- *          entry.get("nationality"));
- *    }
- * }));
- *
+ * {@code
+ * @DataTableType
+ * public User convert(Map<String, String> entry){
+ *    return new User(
+ *        entry.get("firstname"),
+ *        entry.get("lastname")
+ *        entry.get("nationality")
+ *   );
+ * }
+ * }
  * </pre>
  * Then the following Java Step Definition would convert that into an User object:
  * <pre>

java8/README.md

@@ -119,6 +119,9 @@ Jackson to quickly transform well known string representations to Java objects.
  * `DefaultDataTableEntryTransformer`
  * `DefaultDataTableCellTransformer`
 
+For a full list of transformations that can be achieved with data table types
+see [cucumber/datatable](https://github.com/cucumber/cucumber/tree/master/datatable)
+ 
 ```java
 package com.example.app;
 
@@ -186,4 +189,53 @@ public class StepDefinitions implements En {
         });
     }
 }
-```
+```
+
+
+# Transposing Tables
+
+A data table can be transposed by calling `.transpose()`. This means the keys
+will be in the first column rather then the first row.
+
+
+```gherkin
+ Given the user is
+    | firstname	    | Roberto	|
+    | lastname	    | Lo Giacco |
+    | nationality	| Italian	|
+ ```
+
+And a data table type to create a User
+
+```java 
+package com.example.app;
+
+import io.cucumber.datatable.DataTable;
+
+import io.cucumber.java8.En;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Optional;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNotSame;
+import static org.junit.jupiter.api.Assertions.assertSame;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+public class StepDefinitions implements En {
+    
+    public StepDefinitions() {
+        DataTableType((Map<String, String> entry) -> new User(
+            entry.get("firstname"),
+            entry.get("lastname")
+            entry.get("nationality")
+        ));
+    
+        Given("the user is",  (DataTable authorsTable) -> {
+            User user = authorsTable.transpose().asList(User.class);
+            // user  = User(firstname="Roberto", lastname="Lo Giacco", nationality="Italian")
+        });
+    }
+}
+```