more docstrings for the tahoe apis

src/_zkapauthorizer/tahoe.py

@@ -15,6 +15,21 @@ async def upload(
 ) -> Awaitable:  # Awaitable[str] but this requires Python 3.9
     """
     Upload data from the given path and return the resulting capability.
+
+    :param client: An HTTP client to use to make requests to the Tahoe-LAFS
+        HTTP API to perform the upload.
+
+    :param inpath: The path to the regular file to upload.
+
+    :param api_root: The location of the root of the Tahoe-LAFS HTTP API to
+        use to perform the upload.  This should typically be the ``node.url``
+        value from a Tahoe-LAFS client node.
+
+    :return: If the upload is successful then the capability of the uploaded
+        data is returned.
+
+    :raise: If there is a problem uploading the data, some exception is
+        raised.
     """
     with inpath.open() as f:
         resp = await client.put(api_root.child("uri"), f)
@@ -29,6 +44,21 @@ async def download(
 ) -> Awaitable:  # Awaitable[None] but this requires Python 3.9
     """
     Download the object identified by the given capability to the given path.
+
+    :param client: An HTTP client to use to make requests to the Tahoe-LAFS
+        HTTP API to perform the upload.
+
+    :param outpath: The path to the regular file to which the downloaded
+        content will be written.  The content will be written to a temporary
+        file next to this one during download and then moved to this location
+        at the end.
+
+    :param api_root: The location of the root of the Tahoe-LAFS HTTP API to
+        use to perform the upload.  This should typically be the ``node.url``
+        value from a Tahoe-LAFS client node.
+
+    :raise: If there is a problem downloading the data, some exception is
+        raised.
     """
     outtemp = outpath.temporarySibling()
 
@@ -38,5 +68,5 @@ async def download(
             await treq.collect(resp, f.write)
         outtemp.moveTo(outpath)
     else:
-        content = await treq.content(resp)
-        raise Exception(content.decode("utf-8"))
+        content = (await treq.content(resp)).decode("utf-8")
+        raise Exception(content)