More docs for -tty lib types (#1091)

mosaic-tty/src/commonMain/kotlin/com/jakewharton/mosaic/tty/StandardStreams.kt

@@ -71,28 +71,95 @@ public expect class StandardStreams : AutoCloseable {
 	/**
 	 * Write up to [count] bytes from [buffer] at [offset] to the output stream.
 	 * The number of bytes written will be returned.
+	 * This function will continue to write to this process' output stream even if
+	 * [interceptOtherWrites] is called.
 	 */
 	public fun writeOutput(buffer: ByteArray, offset: Int, count: Int): Int
 
 	/**
 	 * Write up to [count] bytes from [buffer] at [offset] to the error stream.
 	 * The number of bytes written will be returned.
+	 * This function will continue to write to this process' error stream even if
+	 * [interceptOtherWrites] is called.
 	 */
 	public fun writeError(buffer: ByteArray, offset: Int, count: Int): Int
 
+	/**
+	 * Begin intercepting writes to the output and errors streams which are NOT performed through this
+	 * type's [writeOutput] and [writeError] functions.
+	 *
+	 * Writes to the "normal" output and error streams (such as through functions like [println]) can
+	 * be read using the functions on the returned [InterceptedStreams] instance. Call
+	 * [InterceptedStreams.close] to restore sending writes to the original output or error stream.
+	 *
+	 * Since intercepting writes changes global process state, subsequent calls to this function
+	 * will throw an exception until [InterceptedStreams.close] is called.
+	 */
 	public fun interceptOtherWrites(): InterceptedStreams
 
 	override fun close()
 
+	/**
+	 * The intercepted process output and error streams which can be read to capture
+	 * inadvertent writes.
+	 * */
 	public class InterceptedStreams : AutoCloseable {
+		/**
+		 * Read up to [count] bytes into [buffer] at [offset] from the intercepted output stream.
+		 * The number of bytes read will be returned. 0 will be returned if [interruptOutputRead] is
+		 * called while waiting for data.
+		 *
+		 * @see readOutputWithTimeout
+		 * @see interruptOutputRead
+		 */
 		public fun readOutput(buffer: ByteArray, offset: Int, count: Int): Int
+
+		/**
+		 * Read up to [count] bytes into [buffer] at [offset] from the intercepted output stream.
+		 * The number of bytes read will be returned. 0 will be returned if [interruptOutputRead] is
+		 * called while waiting for data, or if at least [timeoutMillis] have passed without data.
+		 *
+		 * @param timeoutMillis A value of 0 will perform a non-blocking read. Otherwise, valid values
+		 * are 1 to 999 which represent a maximum time (in milliseconds) to wait for data. Note: This
+		 * value is not validated.
+		 * @see readOutput
+		 * @see interruptOutputRead
+		 */
 		public fun readOutputWithTimeout(buffer: ByteArray, offset: Int, count: Int, timeoutMillis: Int): Int
+
+		/** Signal blocking calls to [readOutput] or [readOutputWithTimeout] to wake up and return 0. */
 		public fun interruptOutputRead()
 
+		/**
+		 * Read up to [count] bytes into [buffer] at [offset] from the intercepted error stream.
+		 * The number of bytes read will be returned. 0 will be returned if [interruptErrorRead] is
+		 * called while waiting for data.
+		 *
+		 * @see readErrorWithTimeout
+		 * @see interruptErrorRead
+		 */
 		public fun readError(buffer: ByteArray, offset: Int, count: Int): Int
+
+		/**
+		 * Read up to [count] bytes into [buffer] at [offset] from the intercepted error stream.
+		 * The number of bytes read will be returned. 0 will be returned if [interruptErrorRead] is
+		 * called while waiting for data, or if at least [timeoutMillis] have passed without data.
+		 *
+		 * @param timeoutMillis A value of 0 will perform a non-blocking read. Otherwise, valid values
+		 * are 1 to 999 which represent a maximum time (in milliseconds) to wait for data. Note: This
+		 * value is not validated.
+		 * @see readError
+		 * @see interruptErrorRead
+		 */
 		public fun readErrorWithTimeout(buffer: ByteArray, offset: Int, count: Int, timeoutMillis: Int): Int
+
+		/** Signal blocking calls to [readError] or [readErrorWithTimeout] to wake up and return 0. */
 		public fun interruptErrorRead()
 
+		/**
+		 * Restore sending writes to the original output or error stream. Discards any unread data in
+		 * the intercepted output and error streams.
+		 */
 		override fun close()
 	}
 }

mosaic-tty/src/commonMain/kotlin/com/jakewharton/mosaic/tty/TestTerminal.kt

@@ -2,9 +2,14 @@ package com.jakewharton.mosaic.tty
 
 import com.jakewharton.mosaic.tty.TestTerminal.Companion.bind
 
+/**
+ * Represents the host-side of a terminal/TTY for testing purposes.
+ *
+ * On Unix-like systems this is a psuedo-TTY (PTY). On Windows it is the current process' Console augmented with
+ * some fake streams.
+ */
 public expect class TestTerminal : AutoCloseable {
 	public companion object {
-
 		/**
 		 * Initialize a [TestTerminal] instance. Only a single [TestTerminal] instance can be bound at
 		 * a time, and only when a [Tty] is not also bound. Subsequent calls will throw an exception

mosaic-tty/src/commonMain/kotlin/com/jakewharton/mosaic/tty/Tty.kt

@@ -79,11 +79,11 @@ public expect class Tty : AutoCloseable {
 	 *
 	 * Note: Before enabling this, consider querying the terminal for support of
 	 * [mode 2048 in-band resize events](https://gist.github.com/rockorager/e695fb2924d36b2bcf1fff4a3704bd83)
-	 * which are more reliable. Mode 2048 events are also parsed and sent as [ResizeEvent]s.
+	 * which are more reliable.
 	 *
 	 * On Windows this enables receiving
 	 * [`WINDOW_BUFFER_SIZE_RECORD`](https://learn.microsoft.com/en-us/windows/console/window-buffer-size-record-str)
-	 * records from the console. Only the row and column values of the [ResizeEvent] will be present.
+	 * records from the console. Only the row and column values of the event will be present.
 	 * The width and height will always be 0.
 	 *
 	 * On Linux and macOS this installs a `SIGWINCH` signal handler which then queries `TIOCGWINSZ`
@@ -104,10 +104,18 @@ public expect class Tty : AutoCloseable {
 	/** Calls [reset] and then frees the resources associated with this instance. */
 	override fun close()
 
+	/** Platform-specific integration callbacks. */
 	public interface Callback {
+		/** Called when the window gains or loses focus. Only invoked on Windows. */
 		public fun onFocus(focused: Boolean)
+
+		/** Currently unused. */
 		public fun onKey()
+
+		/** Currently unused. */
 		public fun onMouse()
+
+		/** If [Tty.enableWindowResizeEvents] was invoked, this is called when the window is resized. */
 		public fun onResize(columns: Int, rows: Int, width: Int, height: Int)
 	}
 }