Document combining items

1 files changed, 20 insertions, 0 deletions

diff --git a/doc/api_misc.rst b/doc/api_misc.rst
index 674ab08..3a68d81 100644
--- a/doc/api_misc.rst
+++ b/doc/api_misc.rst
@@ -24,6 +24,26 @@ Understanding commands
 
 .. automodule:: weatbag.words
 
+Combining items
+---------------
+
+To allow items to be combined to form other items, add a module in ``weatbag.items``
+with the same name as one of the items, replacing spaces with underscores. There,
+define a function called ``combine``, which will take the name of a second
+object. You only need to define this for one object; the game will try to find
+it for both objects being combined.
+
+If the objects can be combined, it should describe what has happened, and return
+a list of the new objects created. Otherwise, it should return ``None``. For
+example, this function is in :mod:`weatbag.items.unlit_torch`::
+
+    def combine(other):
+        if other == 'match':
+            print("The torch sputters into life.")
+            return ['flaming torch']
+        
+        return None
+
 Utility functions
 -----------------