Skip to content

Commit 56f76b1

Browse files
authored
Merge pull request microsoft#209960 from microsoft/tyriar/145234_polish
Polish shellIntegration API docs
2 parents eb736c1 + da612d5 commit 56f76b1

File tree

1 file changed

+48
-23
lines changed

1 file changed

+48
-23
lines changed

src/vscode-dts/vscode.proposed.terminalShellIntegration.d.ts

Lines changed: 48 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -7,30 +7,49 @@ declare module 'vscode' {
77

88
// https://github.com/microsoft/vscode/issues/145234
99

10-
// TODO: Add missing docs
11-
// TODO: Review and polish up all docs
10+
/**
11+
* A command that was executed in a terminal.
12+
*/
1213
export interface TerminalShellExecution {
1314
/**
14-
* The full command line that was executed, including both the command and arguments. The
15-
* {@link TerminalShellExecutionCommandLineConfidence confidence} of this value depends on
16-
* the specific shell's shell integration implementation. This value may become more
17-
* accurate after {@link onDidEndTerminalShellExecution} is fired.
15+
* The command line that was executed. The {@link TerminalShellExecutionCommandLineConfidence confidence}
16+
* of this value depends on the specific shell's shell integration implementation. This
17+
* value may become more accurate after {@link window.onDidEndTerminalShellExecution} is
18+
* fired.
19+
*
20+
* @example
21+
* // Log the details of the command line on start and end
22+
* window.onDidStartTerminalShellExecution(event => {
23+
* const commandLine = event.execution.commandLine;
24+
* console.log(`Command started\n${summarizeCommandLine(commandLine)}`);
25+
* });
26+
* window.onDidEndTerminalShellExecution(event => {
27+
* const commandLine = event.execution.commandLine;
28+
* console.log(`Command ended\n${summarizeCommandLine(commandLine)}`);
29+
* });
30+
* function summarizeCommandLine(commandLine: TerminalShellExecutionCommandLine) {
31+
* return [
32+
* ` Command line: ${command.ommandLine.value}`,
33+
* ` Confidence: ${command.ommandLine.confidence}`,
34+
* ` Trusted: ${command.ommandLine.isTrusted}
35+
* ].join('\n');
36+
* }
1837
*/
1938
readonly commandLine: TerminalShellExecutionCommandLine;
2039

2140
/**
2241
* The working directory that was reported by the shell when this command executed. This
23-
* will be a {@link Uri} if the path reported by the shell can reliably be mapped to the
24-
* connected machine. This requires the shell integration to support working directory
25-
* reporting.
42+
* {@link Uri} may represent a file on another machine (eg. ssh into another machine). This
43+
* requires the shell integration to support working directory reporting.
2644
*/
2745
readonly cwd: Uri | undefined;
2846

2947
/**
3048
* Creates a stream of raw data (including escape sequences) that is written to the
31-
* terminal. This will only include data that was written after `stream` was called for the
32-
* first time, ie. you must call `dataStream` immediately after the command is executed via
33-
* {@link executeCommand} or {@link onDidStartTerminalShellExecution} to not miss any data.
49+
* terminal. This will only include data that was written after `readData` was called for
50+
* the first time, ie. you must call `readData` immediately after the command is executed
51+
* via {@link TerminalShellIntegration.executeCommand} or
52+
* {@link window.onDidStartTerminalShellExecution} to not miss any data.
3453
*
3554
* @example
3655
* // Log all data written to the terminal for a command
@@ -50,24 +69,25 @@ declare module 'vscode' {
5069
/**
5170
* The full command line that was executed, including both the command and its arguments.
5271
*/
53-
value: string;
72+
readonly value: string;
5473

5574
/**
5675
* Whether the command line value came from a trusted source and is therefore safe to
5776
* execute without user additional confirmation, such as a notification that asks "Do you
58-
* want to execute (command)?".
77+
* want to execute (command)?". This verification is likely only needed if you are going to
78+
* execute the command again.
5979
*
60-
* This is false when the command line was reported explicitly by the shell integration
61-
* script (ie. {@link TerminalShellExecutionCommandLineConfidence.High high confidence}),
62-
* but did not include a nonce for verification.
80+
* This is `true` only when the command line was reported explicitly by the shell
81+
* integration script (ie. {@link TerminalShellExecutionCommandLineConfidence.High high confidence})
82+
* and it used a nonce for verification.
6383
*/
64-
isTrusted: boolean;
84+
readonly isTrusted: boolean;
6585

6686
/**
6787
* The confidence of the command line value which is determined by how the value was
6888
* obtained. This depends upon the implementation of the shell integration script.
6989
*/
70-
confidence: TerminalShellExecutionCommandLineConfidence;
90+
readonly confidence: TerminalShellExecutionCommandLineConfidence;
7191
}
7292

7393
/**
@@ -95,15 +115,16 @@ declare module 'vscode' {
95115

96116
/**
97117
* The command line value confidence is high. This means that the value was explicitly sent
98-
* from the shell integration script.
118+
* from the shell integration script or the command was executed via the
119+
* {@link TerminalShellIntegration.executeCommand} API.
99120
*/
100121
High = 2
101122
}
102123

103124
export interface Terminal {
104125
/**
105126
* An object that contains [shell integration](https://code.visualstudio.com/docs/terminal/shell-integration)-powered
106-
* features for the terminal. This will always be undefined immediately after the terminal
127+
* features for the terminal. This will always be `undefined` immediately after the terminal
107128
* is created. Listen to {@link window.onDidActivateTerminalShellIntegration} to be notified
108129
* when shell integration is activated for a terminal.
109130
*
@@ -114,10 +135,14 @@ declare module 'vscode' {
114135
readonly shellIntegration: TerminalShellIntegration | undefined;
115136
}
116137

138+
/**
139+
* [Shell integration](https://code.visualstudio.com/docs/terminal/shell-integration)-powered capabilities owned by a terminal.
140+
*/
117141
export interface TerminalShellIntegration {
118142
/**
119-
* The current working directory of the terminal. This will be a {@link Uri} if the path
120-
* reported by the shell can reliably be mapped to the connected machine.
143+
* The current working directory of the terminal. This {@link Uri} may represent a file on
144+
* another machine (eg. ssh into another machine). This requires the shell integration to
145+
* support working directory reporting.
121146
*/
122147
readonly cwd: Uri | undefined;
123148

0 commit comments

Comments
 (0)