1 files changed, 27 insertions, 17 deletions
diff --git a/shard/lib/manager.ex b/shard/lib/manager.ex
index c3897a3..ed21380 100644
--- a/shard/lib/manager.ex
+++ b/shard/lib/manager.ex
@@ -14,7 +14,8 @@ defprotocol Shard.Manifest do
   """
 
   @doc"""
-  Get the module in question.
+  Get the module that implements the shard. All shard modules must have a function
+  `start_link` that start the shard process and take a single argument: the manifest.
   """
   def module(manifest)
 
@@ -26,29 +27,38 @@ end
 
 defmodule Shard.Manager do
   @moduledoc"""
-    Maintains several important tables :
+  The manager is the main process by which shards are started, stopped, and their lifetime
+  monitored.
 
-    - :shard_db (persistent with DETS)
-    
-      List of
-        { id, manifest, why_have_it, state }
+  Maintains several important tables :
 
-      why_have_it := {:pinned, %MapSet{who requires it...}, %MapSet{who it requires...}}
-                   | {:req, %MapSet{who requires it...}, %MapSet{who it requires...}}
-                   | {:cached, expiry_date}
+  - `@shard_db` (persistent with DETS), a list of:
+  
+    ```
+    { id, manifest, why_have_it, state }
+
+    why_have_it := {:pinned, %MapSet{who requires it...}, %MapSet{who it requires...}}
+                 | {:req, %MapSet{who requires it...}, %MapSet{who it requires...}}
+                 | {:cached, expiry_date}
+    ```
+
+  - `@peer_db` (persistent with DETS), a multi-list of:
 
-    - :peer_db (persistent with DETS)
+    ```
+    { shard_id, peer_info }   # TODO: add health info (last seen, ping, etc)
 
-      Mult-list of
-        { shard_id, peer_info }   # TODO: add health info (last seen, ping, etc)
+    peer_info := {:inet, ip, port}
+    TODO peer_info |= {:inet6, ip, port} | {:onion, name}
+  ```
 
-      peer_info := {:inet, ip, port}
-      TODO peer_info |= {:inet6, ip, port} | {:onion, name}
+  - `:shard_procs` (not persistent), a list of:
 
-    - :shard_procs (not persistent)
+    ```
+    { {id, path}, pid }
+    ```
 
-      List of
-        { {id, path}, pid }
+    The path value is used to distinguish between a shard's main process (`path == nil`)
+    and companion sub-processes such as a page store used by the shard.
   """
 
   use GenServer