From 167765f93289d6b957ec5ce358e597f64b3bdd3c Mon Sep 17 00:00:00 2001
From: Daniel Imms <2193314+Tyriar@users.noreply.github.com>
Date: Fri, 16 Dec 2022 10:53:21 -0800
Subject: [PATCH] Improve IAttributeData jsdoc

Fixes #2603
---
 src/common/Types.d.ts | 38 ++++++++++++++++++++++++++++++++++----
 1 file changed, 34 insertions(+), 4 deletions(-)

diff --git a/src/common/Types.d.ts b/src/common/Types.d.ts
index c4c470ad4a..734715122d 100644
--- a/src/common/Types.d.ts
+++ b/src/common/Types.d.ts
@@ -9,7 +9,7 @@ import { IDeleteEvent, IInsertEvent } from 'common/CircularList';
 import { IParams } from 'common/parser/Types';
 import { ICoreMouseService, ICoreService, IOptionsService, IUnicodeService } from 'common/services/Services';
 import { IBufferSet } from 'common/buffer/Types';
-import { UnderlineStyle } from 'common/buffer/Constants';
+import { Attributes, UnderlineStyle } from 'common/buffer/Constants';
 
 export interface ICoreTerminal {
   coreMouseService: ICoreMouseService;
@@ -133,10 +133,24 @@ export interface IOscLinkData {
   uri: string;
 }
 
-/** Attribute data */
+/**
+ * An object that represents all attributes of a cell.
+ */
 export interface IAttributeData {
+  /**
+   * "fg" is a 32-bit unsigned integer that stores the foreground color of the cell in the 24 least
+   * significant bits and additional flags in the remaining 8 bits.
+   */
   fg: number;
+  /**
+   * "bg" is a 32-bit unsigned integer that stores the background color of the cell in the 24 least
+   * significant bits and additional flags in the remaining 8 bits.
+   */
   bg: number;
+  /**
+   * "extended", aka "ext", stores extended attributes beyond those available in fg and bg. This
+   * data is optional on a cell and encodes less common data.
+   */
   extended: IExtendedAttrs;
 
   clone(): IAttributeData;
@@ -152,8 +166,17 @@ export interface IAttributeData {
   isStrikethrough(): number;
   isProtected(): number;
 
-  // color modes
+  /**
+   * The color mode of the foreground color which determines how to decode {@link getFgColor},
+   * possible values include {@link Attributes.CM_DEFAULT}, {@link Attributes.CM_P16},
+   * {@link Attributes.CM_P256} and {@link Attributes.CM_RGB}.
+   */
   getFgColorMode(): number;
+  /**
+   * The color mode of the background color which determines how to decode {@link getBgColor},
+   * possible values include {@link Attributes.CM_DEFAULT}, {@link Attributes.CM_P16},
+   * {@link Attributes.CM_P256} and {@link Attributes.CM_RGB}.
+   */
   getBgColorMode(): number;
   isFgRGB(): boolean;
   isBgRGB(): boolean;
@@ -163,8 +186,15 @@ export interface IAttributeData {
   isBgDefault(): boolean;
   isAttributeDefault(): boolean;
 
-  // colors
+  /**
+   * Gets an integer representation of the foreground color, how to decode the color depends on the
+   * color mode {@link getFgColorMode}.
+   */
   getFgColor(): number;
+  /**
+   * Gets an integer representation of the background color, how to decode the color depends on the
+   * color mode {@link getBgColorMode}.
+   */
   getBgColor(): number;
 
   // extended attrs