Address documentation Todos and implement missing insert method.

Cleaned up interface arguments for existing insert method too.

src/legacy/core_plugins/console/np_ready/public/application/factories/token_iterator.ts

@@ -16,12 +16,12 @@
  * specific language governing permissions and limitations
  * under the License.
  */
-import { Editor, Position } from '../../interfaces';
+import { CoreEditor, Position } from '../../interfaces';
 import { TokenIteratorImpl } from '../../lib/token_iterator';
 
 interface Dependencies {
   position: Position;
-  editor: Editor;
+  editor: CoreEditor;
 }
 
 export function createTokenIterator({ editor, position }: Dependencies) {

src/legacy/core_plugins/console/np_ready/public/application/models/legacy_editor.ts

@@ -18,13 +18,13 @@
  */
 
 import { Editor as IAceEditor, Range as AceRange } from 'brace';
-import { Editor, Position, Range, Token, TokensProvider } from '../../interfaces';
+import { CoreEditor, Position, Range, Token, TokensProvider } from '../../interfaces';
 import { AceTokensProvider } from '../../lib/ace_token_provider';
 
-export class LegacyEditor implements Editor {
+export class LegacyEditor implements CoreEditor {
   constructor(private readonly editor: IAceEditor) {}
 
-  getLineState({ lineNumber }: { lineNumber: number }) {
+  getLineState(lineNumber: number) {
     const session = this.editor.getSession();
     return session.getState(lineNumber - 1);
   }
@@ -48,7 +48,7 @@ export class LegacyEditor implements Editor {
     return this.editor.getValue();
   }
 
-  getLineValue({ lineNumber }: { lineNumber: number }): string {
+  getLineValue(lineNumber: number): string {
     const session = this.editor.getSession();
     return session.getLine(lineNumber - 1);
   }
@@ -70,8 +70,19 @@ export class LegacyEditor implements Editor {
     return provider.getTokenAt(pos);
   }
 
-  insert(value: string): void {
-    this.editor.insert(value);
+  insert(valueOrPos: string | Position, value?: string): void {
+    if (typeof valueOrPos === 'string') {
+      this.editor.insert(valueOrPos);
+      return;
+    }
+    const document = this.editor.getSession().getDocument();
+    document.insert(
+      {
+        column: valueOrPos.column - 1,
+        row: valueOrPos.lineNumber - 1,
+      },
+      value || ''
+    );
   }
 
   moveCursorToPosition(pos: Position): void {

src/legacy/core_plugins/console/np_ready/public/interfaces/editor.ts → src/legacy/core_plugins/console/np_ready/public/interfaces/core_editor.ts

@@ -53,39 +53,62 @@ export enum LINE_MODE {
   UNKNOWN = 64,
 }
 
-export interface Editor {
+/**
+ * The CoreEditor is a component separate from the Editor implementation that provides Console
+ * app specific business logic. The CoreEditor is an interface to the lower-level editor implementation
+ * being used which is usually vendor code such as Ace or Monaco.
+ */
+export interface CoreEditor {
   /**
-   * Get the current position of the cursor
+   * Get the current position of the cursor.
    */
   getCurrentPosition(): Position;
 
   /**
-   * Get the contents of the editor
+   * Get the contents of the editor.
    */
   getValue(): string;
 
   /**
-   * Get the contents of the editor at a specific line
+   * Get the contents of the editor at a specific line.
    */
-  getLineValue(args: { lineNumber: number }): string;
+  getLineValue(lineNumber: number): string;
 
-  // TODO: document
+  /**
+   * Insert a string value at the current cursor position.
+   */
   insert(value: string): void;
 
-  // TODO: document
+  /**
+   * Insert a string value at the indicated position.
+   */
+  insert(pos: Position, value: string): void;
+
+  /**
+   * Replace a range of text.
+   */
   replace(rangeToReplace: Range, value: string): void;
 
-  // TODO: document
+  /**
+   * Clear the selected range.
+   */
   clearSelection(): void;
 
-  // TODO: document
+  /**
+   * Move the cursor to the indicated position.
+   */
   moveCursorToPosition(pos: Position): void;
 
-  // TODO: document
+  /**
+   * Get the token at the indicated position. The token considered "at" the position is the
+   * one directly preceding the position.
+   *
+   * Returns null if there is no such token.
+   */
   getTokenAt(pos: Position): Token | null;
 
   /**
-   * Get an iterable token provider
+   * Get an iterable token provider.
    */
   getTokenProvider(): TokensProvider;
 
@@ -97,11 +120,10 @@ export interface Editor {
   /**
    * Get the lexer state at the end of a specific line.
    */
-  getLineState(args: { lineNumber: number }): string;
+  getLineState(lineNumber: number): string;
 
-  // TODO: document
+  /**
+   * Get line content between and including the start and end lines provided.
+   */
   getLines(startLine: number, endLine: number): string[];
-
-  // TODO: document
-  // getLineMode(args: { lineNumber: number }): LINE_MODE;
 }

src/legacy/core_plugins/console/np_ready/public/interfaces/index.ts

@@ -17,7 +17,7 @@
  * under the License.
  */
 
-export * from './editor';
+export * from './core_editor';
 export * from './token';
 export * from './token_iterator';
 export * from './tokens_provider';

src/legacy/core_plugins/console/np_ready/public/interfaces/token.ts

@@ -17,13 +17,24 @@
  * under the License.
  */
 
-import { Position } from './editor';
+import { Position } from './core_editor';
 
 export interface Token {
-  // TODO: document
+  /**
+   * The value of the token.
+   *
+   * Can be an empty string.
+   */
   value: string;
-  // TODO: document
+
+  /**
+   * The type of the token. E.g., "whitespace". All of the types are
+   * enumerated by the token lexer.
+   */
   type: string;
-  // TODO: document
+
+  /**
+   * The position of the first character of the token.
+   */
   position: Position;
 }

src/legacy/core_plugins/console/np_ready/public/interfaces/token_iterator.ts

@@ -18,26 +18,56 @@
  */
 
 import { Token } from './token';
-import { Position } from './editor';
+import { Position } from './core_editor';
 
 export interface TokenIterator {
   /**
-   * Report where we are currently
+   * Report the token under the iterator's cursor.
    */
   getCurrentToken(): Token | null;
 
-  // TODO: document
+  /**
+   * Return the current position in the document.
+   *
+   * This will correspond to the position of a token.
+   *
+   * Note: this method may not be that useful given {@link getCurrentToken}.
+   */
+  getCurrentPosition(): Position;
+
+  /**
+   * Go to the previous token in the document.
+   *
+   * Stepping to the previous token can return null under the following conditions:
+   *
+   * 1. We are at the beginning of the document.
+   * 2. The preceding line is empty - no tokens.
+   * 3. We are in an empty document - not text, so no tokens.
+   */
   stepBackward(): Token | null;
 
-  // TODO: document
+  /**
+   * See documentation for {@link stepBackward}.
+   *
+   * Steps forward instead of backwards.
+   */
   stepForward(): Token | null;
 
-  // TODO: document
-  getCurrentPosition(): Position;
-
-  // TODO: document
+  /**
+   * Get the line number of the current token.
+   *
+   * Can be considered a convenience method for:
+   *
+   * ```ts
+   * it.getCurrentToken().lineNumber;
+   * ```
+   */
   getCurrentTokenLineNumber(): number | null;
 
-  // TODO: document
+  /**
+   * See documentation for {@link getCurrentTokenLineNumber}.
+   *
+   * Substitutes `column` for `lineNumber`.
+   */
   getCurrentTokenColumn(): number | null;
 }

src/legacy/core_plugins/console/np_ready/public/interfaces/tokens_provider.ts

@@ -18,7 +18,7 @@
  */
 
 import { Token } from './token';
-import { Position } from './editor';
+import { Position } from './core_editor';
 
 /**
  * Describes a kind of object that provides tokens.
@@ -30,6 +30,15 @@ export interface TokensProvider {
    * - An empty array means that we are on an empty line.
    */
   getTokens(lineNumber: number): Token[] | null;
-  // TODO: document
+
+  /**
+   * Get the token at the specified position.
+   *
+   * The token "at" the position is considered to the token directly preceding
+   * the indicated cursor position.
+   *
+   * Returns null if there is not a token that meets this criteria of if the position is outside
+   * of the document range.
+   */
   getTokenAt(pos: Position): Token | null;
 }

src/legacy/core_plugins/console/public/quarantined/src/autocomplete.ts

@@ -370,9 +370,7 @@ export default function({
       } else {
         indentedTemplateLines = utils.jsonToString(term.template, true).split('\n');
       }
-      let currentIndentation = editor.getLineValue({
-        lineNumber: context.rangeToReplace.start.lineNumber,
-      });
+      let currentIndentation = editor.getLineValue(context.rangeToReplace.start.lineNumber);
       currentIndentation = currentIndentation.match(/^\s*/)![0];
       for (
         let i = 1;
@@ -560,7 +558,7 @@ export default function({
     }
 
     // in between request on an empty
-    if ((editor.getLineValue({ lineNumber: pos.lineNumber }) || '').trim() === '') {
+    if (editor.getLineValue(pos.lineNumber).trim() === '') {
       // check if the previous line is a single line begging of a new request
       rowMode = parser.getRowParseMode(
         pos.lineNumber - 1 - 1 /* see RowParser for why the added -1, for now */