From 77f71985d4319c8882ac512f0c30ebc868ff07ab Mon Sep 17 00:00:00 2001
From: John-Mark Gurney <jmg@funkthat.com>
Date: Sun, 13 Dec 2020 15:41:32 -0800
Subject: [PATCH] add a bunch of doc strings..  still more to come, but
 discovered a test coverage bug..

---
 wsfwd/__init__.py | 64 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 63 insertions(+), 1 deletion(-)

diff --git a/wsfwd/__init__.py b/wsfwd/__init__.py
index 438aa78..50d1dd3 100644
--- a/wsfwd/__init__.py
+++ b/wsfwd/__init__.py
@@ -40,7 +40,20 @@ class TestTimeout(unittest.IsolatedAsyncioTestCase):
 			await somefun()
 
 class WFProcess:
+	'''
+	This implements a similar interface to the Process interface
+	as documented at:
+	https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.asyncio.subprocess.Process
+	'''
+
 	def __init__(self, client, stdin, stdout):
+		'''
+		client must be an instance of WSFWDClient.
+		stdin and stdout are the objects implementing the
+		StreamWriter and StreamReader interfaces as defined
+		by the asyncio interface.
+		'''
+
 		self._client = client
 		self._stdin = stdin
 		self._stdout = stdout
@@ -48,6 +61,14 @@ class WFProcess:
 		self._retcode_waiters = []
 
 	def set_returncode(self, retcode):
+		'''
+		This is to be called by WSFWDClient when it receives
+		the the exit command.
+
+		It will set the returcode property, and wait up any
+		waiters that are waiting in wait.
+		'''
+
 		if self._returncode is not None:
 			raise RuntimeError('return code already set')
 
@@ -64,17 +85,33 @@ class WFProcess:
 
 	@property
 	def returncode(self):
+		'''
+		https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.asyncio.subprocess.Process.returncode
+		'''
+
 		return self._returncode
 
 	@property
 	def stdin(self):
+		'''
+		https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.asyncio.subprocess.Process.stdin
+		'''
+
 		return self._stdin
 
 	@property
 	def stdout(self):
+		'''
+		https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.asyncio.subprocess.Process.stdout
+		'''
+
 		return self._stdout
 
 	async def wait(self):
+		'''
+		https://docs.python.org/3/library/asyncio-subprocess.html#asyncio.asyncio.subprocess.Process.wait
+		'''
+
 		if self.returncode is not None:
 			return self.returncode
 
@@ -88,7 +125,8 @@ class WFProcess:
 				self._retcode_waiters.remove(fut)
 
 class WFStreamWriter:
-	'''This emulates asyncio.StreamWriter.
+	'''This emulates asyncio.StreamWriter.  For more info, see:
+	https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter
 
 	The following methods/properties are not implemented:
 	    can_write_eof, write_eof, transport, get_extra_info
@@ -100,29 +138,53 @@ class WFStreamWriter:
 		self._closed = False
 
 	def write(self, data):
+		'''
+		https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter.write
+		'''
+
 		return self.writelines([ data ])
 
 	def writelines(self, data):
+		'''
+		https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter.writelines
+		'''
+
 		if self._closed:
 			raise RuntimeError('stream is closed')
 
 		self._client.sendstream(self._stream, *data)
 
 	async def drain(self):
+		'''
+		https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter.drain
+		'''
+
 		if self._closed:
 			raise RuntimeError('stream is closed')
 
 		await self._client.drain(self._stream)
 
 	def is_closing(self):
+		'''
+		https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter.is_closing
+		'''
+
 		return self._closed
 
 	def close(self):
+		'''
+		https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter.close
+		'''
+
 		self._closed = True
 
 		self._closetask = asyncio.create_task(self._client._sendcmd(dict(cmd='chanclose', chan=self._stream)))
 
 	async def wait_closed(self):
+		'''
+		https://docs.python.org/3/library/asyncio-stream.html#asyncio.StreamWriter.wait_closed
+		'''
+
 		pass
 
 class WSFWDCommon: