Skip to content

Commit a0c10ac

Browse files
iclantoniclanton
authored
Merge pull request microsoft#1079 from iclanton/ianc/documentation-for-StringBufferTerminalProvider
[node-core-library] Include some missing documentation.
2 parents ba6fc44 + cb7063f commit a0c10ac

5 files changed

Lines changed: 58 additions & 15 deletions

File tree

‎common/changes/@microsoft/node-core-library/ianc-documentation-for-StringBufferTerminalProvider_2019-02-07-04-18.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"changes": [
3+
{
4+
"comment": "",
5+
"packageName": "@microsoft/node-core-library",
6+
"type": "none"
7+
}
8+
],
9+
"packageName": "@microsoft/node-core-library",
10+
"email": "iclanton@users.noreply.github.com"
11+
}

‎common/reviews/api/node-core-library.api.ts‎

Lines changed: 3 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
// @beta
22
class Colors {
3-
// @internal (undocumented)
3+
// @internal
44
static _normalizeStringOrColorableSequence(value: string | IColorableSequence): IColorableSequence;
55
// (undocumented)
66
static black(text: string | IColorableSequence): IColorableSequence;
@@ -40,16 +40,12 @@ class Colors {
4040
static yellowBackground(text: string | IColorableSequence): IColorableSequence;
4141
}
4242

43-
// @beta (undocumented)
43+
// @beta
4444
class ConsoleTerminalProvider implements ITerminalProvider {
4545
constructor(options?: Partial<IConsoleTerminalProviderOptions>);
46-
// (undocumented)
4746
readonly eolCharacter: string;
48-
// (undocumented)
4947
readonly supportsColor: boolean;
50-
// (undocumented)
5148
verboseEnabled: boolean;
52-
// (undocumented)
5349
write(data: string, severity: TerminalProviderSeverity): void;
5450
}
5551

@@ -416,22 +412,15 @@ class Sort {
416412
static sortSetBy<T>(set: Set<T>, keySelector: (element: T) => any, keyComparer?: (x: T, y: T) => number): void;
417413
}
418414

419-
// @beta (undocumented)
415+
// @beta
420416
class StringBufferTerminalProvider implements ITerminalProvider {
421417
constructor(supportsColor?: boolean);
422-
// (undocumented)
423418
readonly eolCharacter: string;
424-
// (undocumented)
425419
getErrorOutput(): string;
426-
// (undocumented)
427420
getOutput(): string;
428-
// (undocumented)
429421
getVerbose(): string;
430-
// (undocumented)
431422
getWarningOutput(): string;
432-
// (undocumented)
433423
readonly supportsColor: boolean;
434-
// (undocumented)
435424
write(data: string, severity: TerminalProviderSeverity): void;
436425
}
437426

‎libraries/node-core-library/src/Terminal/Colors.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -167,6 +167,9 @@ export class Colors {
167167
}
168168

169169
/**
170+
* If called with a string, returns the string wrapped in a {@link IColorableSequence}.
171+
* If called with a {@link IColorableSequence}, returns the {@link IColorableSequence}.
172+
*
170173
* @internal
171174
*/
172175
public static _normalizeStringOrColorableSequence(value: string | IColorableSequence): IColorableSequence {
@@ -178,4 +181,4 @@ export class Colors {
178181
return value;
179182
}
180183
}
181-
}
184+
}

‎libraries/node-core-library/src/Terminal/ConsoleTerminalProvider.ts‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,24 @@ export interface IConsoleTerminalProviderOptions {
1919
}
2020

2121
/**
22+
* Terminal provider that prints to STDOUT (for log- and verbose-level messages) and
23+
* STDERR (for warning- and error-level messsages).
24+
*
2225
* @beta
2326
*/
2427
export class ConsoleTerminalProvider implements ITerminalProvider {
28+
/**
29+
* If true, verbose-level messages should be written to the console.
30+
*/
2531
public verboseEnabled: boolean = false;
2632

2733
public constructor(options: Partial<IConsoleTerminalProviderOptions> = {}) {
2834
this.verboseEnabled = !!options.verboseEnabled;
2935
}
3036

37+
/**
38+
* {@inheritdoc ITerminalProvider.write}
39+
*/
3140
public write(data: string, severity: TerminalProviderSeverity): void {
3241
switch (severity) {
3342
case TerminalProviderSeverity.warning:
@@ -51,10 +60,16 @@ export class ConsoleTerminalProvider implements ITerminalProvider {
5160
}
5261
}
5362

63+
/**
64+
* {@inheritdoc ITerminalProvider.eolCharacter}
65+
*/
5466
public get eolCharacter(): string {
5567
return EOL;
5668
}
5769

70+
/**
71+
* {@inheritdoc ITerminalProvider.supportsColor}
72+
*/
5873
public get supportsColor(): boolean {
5974
return supportsColor;
6075
}

‎libraries/node-core-library/src/Terminal/StringBufferTerminalProvider.ts‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,10 @@ import { StringBuilder } from '../StringBuilder';
66
import { Text } from '../Text';
77

88
/**
9+
* Terminal provider that stores written data in buffers separated by severity.
10+
* This terminal provider is designed to be used when code that prints to a terminal
11+
* is being unit tested.
12+
*
913
* @beta
1014
*/
1115
export class StringBufferTerminalProvider implements ITerminalProvider {
@@ -20,6 +24,9 @@ export class StringBufferTerminalProvider implements ITerminalProvider {
2024
this._supportsColor = supportsColor;
2125
}
2226

27+
/**
28+
* {@inheritdoc ITerminalProvider.write}
29+
*/
2330
public write(data: string, severity: TerminalProviderSeverity): void {
2431
switch (severity) {
2532
case TerminalProviderSeverity.warning: {
@@ -45,26 +52,44 @@ export class StringBufferTerminalProvider implements ITerminalProvider {
4552
}
4653
}
4754

55+
/**
56+
* {@inheritdoc ITerminalProvider.eolCharacter}
57+
*/
4858
public get eolCharacter(): string {
4959
return '[n]';
5060
}
5161

62+
/**
63+
* {@inheritdoc ITerminalProvider.supportsColor}
64+
*/
5265
public get supportsColor(): boolean {
5366
return this._supportsColor;
5467
}
5568

69+
/**
70+
* Get everything that has been written at log-level severity.
71+
*/
5672
public getOutput(): string {
5773
return this._normalizeOutput(this._standardBuffer.toString());
5874
}
5975

76+
/**
77+
* Get everything that has been written at verbose-level severity.
78+
*/
6079
public getVerbose(): string {
6180
return this._normalizeOutput(this._verboseBuffer.toString());
6281
}
6382

83+
/**
84+
* Get everything that has been written at error-level severity.
85+
*/
6486
public getErrorOutput(): string {
6587
return this._normalizeOutput(this._errorBuffer.toString());
6688
}
6789

90+
/**
91+
* Get everything that has been written at warning-level severity.
92+
*/
6893
public getWarningOutput(): string {
6994
return this._normalizeOutput(this._warningBuffer.toString());
7095
}

0 commit comments

Comments
 (0)