Merge pull request #2 from goatfryed/chore/project-cleanups

docs: fill TODO sections in docs
goatfryed · Sep 29, 2024 · 95561fb · 95561fb
2 parents 282ceeb + 1eea055
commit 95561fb
Show file tree

Hide file tree

Showing 6 changed files with 61 additions and 6 deletions.
diff --git a/README.md b/README.md
@@ -39,7 +39,7 @@ All formats are optional dependencies.
 #### Include in your project
 For gradle capabilities can be used
 ```groovy
-implementation("com.github.goatfryed:assert-baseline:1.0.0-alpha1-SNAPSHOT") {
+implementation("com.github.goatfryed:assert-baseline:{version}") {
   capabilities {
      requireCapability("com.github.goatfryed:assert-baseline-{format}")
   }
@@ -52,12 +52,14 @@ For maven
     <dependency>
         <groupId>com.github.goatfryed</groupId>
         <artifactId>assert-baseline</artifactId>
-        <version>1.0.0-alpha1-SNAPSHOT</version>
+        <version>{version}</version>
     </dependency>
     <!-- check the optional dependencies of your format -->
 </dependencies>
 ````
 
+See [releases](https://github.com/goatfryed/assert-baseline/releases) for the latest release version.
+
 #### Writing assertions
 ```java
 import static com.github.goatfryed.assert_baseline.Assertions.assertThatJson;

diff --git a/docs/assert-json-baseline.md b/docs/assert-json-baseline.md
@@ -24,7 +24,7 @@ For maven
     <dependency>
         <groupId>com.github.goatfryed</groupId>
         <artifactId>assert-baseline</artifactId>
-        <version>1.0.0-alpha1-SNAPSHOT</version>
+        <version>{version}</version>
     </dependency>
     <dependency>
         <groupId>net.javacrumbs.json-unit</groupId>

diff --git a/docs/assert-text-baseline.md b/docs/assert-text-baseline.md
@@ -1 +1,29 @@
-[TODO]
+# Text Assertions
+String assertions require no additional dependency and use simply assertJ.
+
+```java
+import static com.github.goatfryed.assert_baseline.Assertions.assertThatJson;
+
+assertThatText(yourString)
+    .isEqualToBaseline("src/test/resources/specs/my.baseline.txt");
+```
+
+## Include in your project
+For gradle
+```groovy
+    implementation("com.github.goatfryed:assert-baseline:1.0.0-alpha1-SNAPSHOT") {}
+```
+
+For maven
+````xml
+<dependencies>
+    <dependency>
+        <groupId>com.github.goatfryed</groupId>
+        <artifactId>assert-baseline</artifactId>
+        <version>{version}</version>
+    </dependency>
+</dependencies>
+````
+
+## Tips & Recipies
+`usingTextComparator` is simply an alias for `usingComparator` of assertJ on String subjects
diff --git a/docs/assert-xml-baseline.md b/docs/assert-xml-baseline.md
@@ -24,7 +24,7 @@ For maven
     <dependency>
         <groupId>com.github.goatfryed</groupId>
         <artifactId>assert-baseline</artifactId>
-        <version>1.0.0-alpha1-SNAPSHOT</version>
+        <version>{version}</version>
     </dependency>
     <dependency>
         <groupId>org.xmlunit</groupId>

diff --git a/docs/extend-assert-baseline.md b/docs/extend-assert-baseline.md
@@ -1,2 +1,21 @@
 # Extend with another baseline format
-[TODO]
+
+You can extend [AbstractBaselineAssertion](../src/main/java/io/github/goatfryed/assert_baseline/core/AbstractBaselineAssertion.java)
+to implement your own format.
+
+Compare [JsonBaselineAssertion](../src/main/java/io/github/goatfryed/assert_baseline/json/JsonBaselineAssertion.java)
+
+(!) This internal API is considered unstable.
+
+## Extending from AbstractBaselineAssertion
+
+### 1. implement write
+Implement `AbstractBaselineAssertion::saveActual(BaselineContext)`.
+Serialize your subject and write it to `BaselineContext::getActualOutputStream`
+
+### 2. implement verification
+Implement `verifyIsEqualToBaseline(BaselineContext context)`.
+Usually, you'll want to read from `BaselineContext::getBaselineAsString(), deserialize the baseline,
+and then compare the java beans.
+
+### implement further conventional methods
diff --git a/src/main/java/io/github/goatfryed/assert_baseline/core/AbstractBaselineAssertion.java b/src/main/java/io/github/goatfryed/assert_baseline/core/AbstractBaselineAssertion.java
@@ -39,8 +39,14 @@ public final SELF usingStorage(Configurer<StorageFactory> configurer) {
         return myself;
     }
 
+    /**
+     * Expects you to write your subject in serialized form to {@link BaselineContext#getActualOutputStream()}
+     */
     abstract protected void saveActual(BaselineContext context);
 
+    /**
+     * Usually, you'll want to read {@link BaselineContext#getBaselineAsString()}, deserialize the baseline and compare the models.
+     */
     abstract protected void verifyIsEqualToBaseline(BaselineContext context);
 
     private BaselineContextFactory getContextFactory() {