doc improvements

src/_zkapauthorizer/_storage_server.py

@@ -426,10 +426,11 @@ def get_slot_share_size(storage_server, storage_index, sharenums):
                 else:
                     # Compared to calculating how much *user* data we're
                     # storing, the on-disk file is larger by at *least*
-                    # SLOT_HEADER_SIZE* where various bookkeeping is kept.
-                    # There is also a variable sized trailer which is harder
-                    # to compute.  Fortunately it's generally also a lot
-                    # smaller so I'm just going to ignore it for now.
+                    # SLOT_HEADER_SIZE.  There is also a variable sized
+                    # trailer which is harder to compute but which is at least
+                    # LEASE_TRAILER_SIZE.  Fortunately it's often exactly
+                    # LEASE_TRAILER_SIZE so I'm just going to ignore it for
+                    # now.
                     #
                     # By measuring that the slots are larger than the data the
                     # user is storing we'll overestimate how many passes are

src/_zkapauthorizer/tests/test_storage_server.py

@@ -203,8 +203,23 @@ class PassValidationTests(TestCase):
             self.fail("expected MorePassesRequired, got {}".format(result))
 
 
-    def _test_extend_mutable_fails_without_passes(self, storage_index, secrets, test_and_write_vectors_for_shares, make_data_vector):
-        # Hypothesis causes our storage server to be used many times.  Clean
+    def _test_extend_mutable_fails_without_passes(
+            self,
+            storage_index,
+            secrets,
+            test_and_write_vectors_for_shares,
+            make_data_vector,
+    ):
+        """
+        Verify that increasing the storage requirements of a slot without
+        supplying more passes fails.
+
+        :param make_data_vector: A one-argument callable.  It will be called
+            with the current length of a slot share.  It should return a write
+            vector which will increase the storage requirements of that slot
+            share by at least BYTES_PER_PASS.
+        """
+        # hypothesis causes our storage server to be used many times.  Clean
         # up between iterations.
         cleanup_storage_server(self.anonymous_storage_server)