From fac025367b161ce072b29d62ac9883b6317d4cad Mon Sep 17 00:00:00 2001
From: Daniel Imms <daimms@microsoft.com>
Date: Tue, 4 Feb 2020 08:15:21 -0800
Subject: [PATCH] Document IBufferCell members

---
 typings/xterm.d.ts | 82 +++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 77 insertions(+), 5 deletions(-)

diff --git a/typings/xterm.d.ts b/typings/xterm.d.ts
index 067ffc31..5f97cf10 100644
--- a/typings/xterm.d.ts
+++ b/typings/xterm.d.ts
@@ -1008,30 +1008,102 @@ declare module 'xterm' {
    * Represents a single cell in the terminal's buffer.
    */
   interface IBufferCell {
+    /**
+     * The width of the character. Some examples:
+     *
+     * - `1` for most cells.
+     * - `2` for wide character like CJK glyphs.
+     * - `0` for cells immediately following cells with a width of `2`.
+     */
     getWidth(): number;
+
+    /**
+     * The character(s) within the cell. Examples of what this can contain:
+     *
+     * - A normal width character
+     * - A wide character (eg. CJK)
+     * - An emoji
+     */
     getChars(): string;
+
+    /**
+     * Gets the UTF32 codepoint of single characters, if content is a combined
+     * string it returns the codepoint of the last character in the string.
+     */
     getCode(): number;
 
+    /**
+     * Gets the number representation of the foreground color mode, this can be
+     * used to perform quick comparisons of 2 cells to see if they're the same.
+     * Use `isFgRGB`, `isFgPalette` and `isFgDefault` to check what color mode
+     * a cell is.
+     */
     getFgColorMode(): number;
+
+    /**
+     * Gets the number representation of the background color mode, this can be
+     * used to perform quick comparisons of 2 cells to see if they're the same.
+     * Use `isBgRGB`, `isBgPalette` and `isBgDefault` to check what color mode
+     * a cell is.
+     */
     getBgColorMode(): number;
+
+    /**
+     * Gets a cell's foreground color number, this differs depending on what the
+     * color mode of the cell is:
+     *
+     * - Default: This should be 0, representing the default foreground color
+     *   (CSI 39 m).
+     * - Palette: This is a number from 0 to 255 of ANSI colors (CSI 3(0-7) m,
+     *   CSI 9(0-7) m, CSI 38 ; 5 ; 0-255 m).
+     * - RGB: A hex value representing a 'true color': 0xRRGGBB.
+     *   (CSI 3 8 ; 2 ; Pi ; Pr ; Pg ; Pb)
+     */
     getFgColor(): number;
+
+    /**
+     * Gets a cell's background color number, this differs depending on what the
+     * color mode of the cell is:
+     *
+     * - Default: This should be 0, representing the default background color
+     *   (CSI 49 m).
+     * - Palette: This is a number from 0 to 255 of ANSI colors
+     *   (CSI 4(0-7) m, CSI 10(0-7) m, CSI 48 ; 5 ; 0-255 m).
+     * - RGB: A hex value representing a 'true color': 0xRRGGBB
+     *   (CSI 4 8 ; 2 ; Pi ; Pr ; Pg ; Pb)
+     */
     getBgColor(): number;
 
-    isInverse(): number;
+    /** Whether the cell has the bold attribute (CSI 1 m). */
     isBold(): number;
-    isUnderline(): number;
-    isBlink(): number;
-    isInvisible(): number;
+    /** Whether the cell has the inverse attribute (CSI 3 m). */
     isItalic(): number;
+    /** Whether the cell has the inverse attribute (CSI 2 m). */
     isDim(): number;
+    /** Whether the cell has the underline attribute (CSI 4 m). */
+    isUnderline(): number;
+    /** Whether the cell has the inverse attribute (CSI 5 m). */
+    isBlink(): number;
+    /** Whether the cell has the inverse attribute (CSI 7 m). */
+    isInverse(): number;
+    /** Whether the cell has the inverse attribute (CSI 8 m). */
+    isInvisible(): number;
 
+    /** Whether the cell is using the RGB foreground color mode. */
     isFgRGB(): boolean;
+    /** Whether the cell is using the RGB background color mode. */
     isBgRGB(): boolean;
+    /** Whether the cell is using the palette foreground color mode. */
     isFgPalette(): boolean;
+    /** Whether the cell is using the palette background color mode. */
     isBgPalette(): boolean;
-    isAttributeDefault(): boolean;
+    /** Whether the cell is using the default foreground color mode. */
     isFgDefault(): boolean;
+    /** Whether the cell is using the default background color mode. */
     isBgDefault(): boolean;
+
+    /** Whether the cell has the default attribute (no color or style). */
+    isAttributeDefault(): boolean;
   }
 
   /**