From: Paris Kasidiaris <paris@sourcelair.com>
Date: Fri, 14 Jul 2017 07:07:33 +0000 (+0300)
Subject: Improve documentation of `Buffer` and `BufferSet` classes
X-Git-Url: https://git.proxmox.com/?a=commitdiff_plain;h=58b9f712df21c551bb9b3d661fdefc9ecbd03ce6;p=mirror_xterm.js.git

Improve documentation of `Buffer` and `BufferSet` classes
---

diff --git a/src/Buffer.ts b/src/Buffer.ts
index 51ee0f1..256f6c9 100644
--- a/src/Buffer.ts
+++ b/src/Buffer.ts
@@ -6,16 +6,20 @@ import { ITerminal } from './Interfaces';
 import { CircularList } from './utils/CircularList';
 
 /**
- * This class represents a terminal buffer (an internal state of the terminal)/
+ * This class represents a terminal buffer (an internal state of the terminal), where the
+ * following information is stored (in high-level):
+ *   - text content of this particular buffer
+ *   - cursor position
+ *   - scroll position
  */
 export class Buffer {
   public lines: CircularList<[string, number, string]>;
 
   /**
    * Create a new Buffer.
-   * @param {Terminal} terminal - The terminal the buffer will belong to
-   * @param {number} ydisp - The scroll position of the buffer in the viewport
-   * @param {number} ybase - The scroll position of the y cursor (ybase + y = the y position within the buffer)
+   * @param {Terminal} terminal - The terminal the Buffer will belong to
+   * @param {number} ydisp - The scroll position of the Buffer in the viewport
+   * @param {number} ybase - The scroll position of the y cursor (ybase + y = the y position within the Buffer)
    * @param {number} y - The cursor's y position after ybase
    * @param {number} x - The cursor's x position after ybase
    */
diff --git a/src/BufferSet.ts b/src/BufferSet.ts
index c9022a9..d4a471a 100644
--- a/src/BufferSet.ts
+++ b/src/BufferSet.ts
@@ -6,11 +6,19 @@ import { ITerminal } from './Interfaces';
 import { Buffer } from './Buffer';
 import { EventEmitter } from './EventEmitter';
 
+/**
+ * The BufferSet represents the set of two buffers used by xterm terminals (normal and alt) and
+ * provides also utilities for working with them.
+ */
 export class BufferSet extends EventEmitter {
   private _normal: Buffer;
   private _alt: Buffer;
   private _activeBuffer: Buffer;
 
+  /**
+   * Create a new BufferSet for the given terminal.
+   * @param {Terminal} terminal - The terminal the BufferSet will belong to
+   */
   constructor(private _terminal: ITerminal) {
     super();
     this._normal = new Buffer(this._terminal);
@@ -18,25 +26,43 @@ export class BufferSet extends EventEmitter {
     this._activeBuffer = this._normal;
   }
 
+  /**
+   * Returns the alt Buffer of the BufferSet
+   * @returns {Buffer}
+   */
   public get alt(): Buffer {
     return this._alt;
   }
 
+  /**
+   * Returns the normal Buffer of the BufferSet
+   * @returns {Buffer}
+   */
   public get active(): Buffer {
     return this._activeBuffer;
   }
 
+  /**
+   * Returns the currently active Buffer of the BufferSet
+   * @returns {Buffer}
+   */
   public get normal(): Buffer {
     return this._normal;
   }
 
+  /**
+   * Sets the normal Buffer of the BufferSet as its currently active Buffer
+   */
   public activateNormalBuffer(): void {
     this._activeBuffer = this._normal;
-    this.emit('activate', this._normal); // todo maybe simpler this._terminal.buffer = this._terminal.buffers.normal than using EventEmitter?
+    this.emit('activate', this._normal);
   }
 
+  /**
+   * Sets the alt Buffer of the BufferSet as its currently active Buffer
+   */
   public activateAltBuffer(): void {
     this._activeBuffer = this._alt;
-    this.emit('activate', this._alt); // todo maybe simpler this._terminal.buffer = this._terminal.buffers.alt than using EventEmitter?
+    this.emit('activate', this._alt);
   }
 }