From 7d218ec8ce8e2150ec7ae5c5f8a629ed349c9403 Mon Sep 17 00:00:00 2001
From: Valentin Lorentz <progval+git@progval.net>
Date: Thu, 26 Sep 2019 22:47:04 +0200
Subject: [PATCH] Document unpreserve.Reader (expected format + method hooks).

---
 src/unpreserve.py | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/src/unpreserve.py b/src/unpreserve.py
index 66f9dca1f..434b80a47 100644
--- a/src/unpreserve.py
+++ b/src/unpreserve.py
@@ -28,6 +28,35 @@
 ###
 
 class Reader(object):
+    """Opens a file and reads it in blocks, using the `Creator` class to
+    instantiate an object for each of the blocks.
+
+    The format is of the form:
+
+    ```
+    entry_type entry_id1:
+      command1 arg1 arg1b
+      command2 arg2
+
+    entry_type entry_id2:
+      command3 arg3 arg13
+    ```
+
+    When reading this file, the `Creator` will be instantiated with the
+    provided args and kwargs to a `creator` object, whose methods will then
+    be called in this pattern:
+
+    ```
+    creator.entry_type("entry_id1", 1)
+    creator.command1("arg1 arg1b", 2)
+    creator.command2("arg2", 3)
+    creator.finish()
+
+    creator.entry_type'entry_id2", 5)
+    creator.command3("arg3 arg3b", 6)
+    creator.finish()
+    ```
+    """
     def __init__(self, Creator, *args, **kwargs):
         self.Creator = Creator
         self.args = args