From bae15f1da52dd225d41242e14df71e90745867ea Mon Sep 17 00:00:00 2001
From: Daniel Imms <daimms@microsoft.com>
Date: Sat, 16 Jun 2018 12:54:30 +0200
Subject: [PATCH] Improve documentation of terminal renderer APIs

---
 src/vs/vscode.proposed.d.ts | 37 +++++++++++++++++++++++++++++++------
 1 file changed, 31 insertions(+), 6 deletions(-)

diff --git a/src/vs/vscode.proposed.d.ts b/src/vs/vscode.proposed.d.ts
index af7e630a04d4..ca6ae5b24616 100644
--- a/src/vs/vscode.proposed.d.ts
+++ b/src/vs/vscode.proposed.d.ts
@@ -344,19 +344,44 @@ declare module 'vscode' {
 		onData: Event<string>;
 	}
 
-	// A TerminalRender does not own a process, it's similar to an output window
-	// but it understands ANSI
+	/**
+	 * Represents a terminal without a process where all interaction and output in the terminal is
+	 * controlled by an extension. This is similar to an output window but has the same VT sequence
+	 * compatility as the regular terminal.
+	 */
 	export interface TerminalRenderer {
-		// Extensions can set the name (what appears in the dropdown)
+		/**
+		 * The name of the terminal, this will appear in the terminal selector.
+		 */
 		name: string;
 
 		// Setting to undefined will reset to use the maximum available
 		// dimensions: TerminalDimensions;
 
-		// Write to the terminal emulator
-		write(data: string): void; // out
+		/**
+		 * Write text to the terminal. Unlike [Terminal.sendText](#Terminal.sendText) which sends
+		 * text to the underlying _process_, this will write the text to the terminal itself.
+		 *
+		 * **Example:** Write red text to the terminal
+		 * ```typescript
+		 * terminalRenderer.write('\x1b[31mHello world\x1b[0m');
+		 * ```
+		 *
+		 * **Example:** Move the cursor to the 10th row and 20th column and write an asterisk
+		 * ```typescript
+		 * terminalRenderer.write('\x1b[10;20H*');
+		 * ```
+		 *
+		 * @param text The text to write.
+		 */
+		write(text: string): void; // out
 
-		// key press, or sendText was triggered by an extension on the terminal
+		// TODO: Should this be onInput instead?
+		/**
+		 * An event which fires on keystrokes in the terminal or when an extension calls
+		 * [Terminal.sendText](#Terminal.sendText). Keystrokes are converted into their
+		 * corresponding VT sequence representation.
+		 */
 		onData: Event<string>; // in
 
 		// Fires when the panel area is resized, this DOES NOT fire when `dimensions` is set