From 1eea055488fc84baf3c2cbe62646d556bfe3cfd0 Mon Sep 17 00:00:00 2001
From: "Omar \"Goatfryed\" Sood" <goatfryed@gmail.com>
Date: Sun, 29 Sep 2024 22:53:25 +0200
Subject: [PATCH] docs: document how to extend

---
 docs/extend-assert-baseline.md                | 21 ++++++++++++++++++-
 .../core/AbstractBaselineAssertion.java       |  6 ++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/extend-assert-baseline.md b/docs/extend-assert-baseline.md
index d8a9b65..e2bcdaf 100644
--- a/docs/extend-assert-baseline.md
+++ b/docs/extend-assert-baseline.md
@@ -1,2 +1,21 @@
 # Extend with another baseline format
-[TODO]
\ No newline at end of file
+
+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
index b07e1d5..540775f 100644
--- 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() {