Skip to content

Commit f1cc8e4

Browse files
Ortaandrewbranch
Orta
and
andrewbranch
authored
[minor] Adds some docs to the LSP interface (microsoft#36740)
* Adds some docs to the LSP dts * Ensure that getProgramDiagnostic is included everywhere that getCompilerOptionsDiagnostic is * Update baselines * Apply suggestions from code review Co-Authored-By: Andrew Branch <andrewbranch@users.noreply.github.com> * Remove the getCompilerOptionsDiagnostics -> getProgramDiagnostics change Co-authored-by: Andrew Branch <andrewbranch@users.noreply.github.com>
1 parent eaeee9c commit f1cc8e4

4 files changed

Lines changed: 215 additions & 23 deletions

File tree

‎src/harness/harnessLanguageService.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -520,7 +520,6 @@ namespace Harness.LanguageService {
520520
getNavigationTree(fileName: string): ts.NavigationTree {
521521
return unwrapJSONCallResult(this.shim.getNavigationTree(fileName));
522522
}
523-
524523
getOutliningSpans(fileName: string): ts.OutliningSpan[] {
525524
return unwrapJSONCallResult(this.shim.getOutliningSpans(fileName));
526525
}

‎src/services/types.ts‎

Lines changed: 75 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -289,43 +289,110 @@ namespace ts {
289289
// with a language service host instance
290290
//
291291
export interface LanguageService {
292+
/** This is used as a part of restarting the language service. */
292293
cleanupSemanticCache(): void;
293294

295+
/**
296+
* Gets errors indicating invalid syntax in a file.
297+
*
298+
* In English, "this cdeo have, erorrs" is syntactically invalid because it has typos,
299+
* grammatical errors, and misplaced punctuation. Likewise, examples of syntax
300+
* errors in TypeScript are missing parentheses in an `if` statement, mismatched
301+
* curly braces, and using a reserved keyword as a variable name.
302+
*
303+
* These diagnostics are inexpensive to compute and don't require knowledge of
304+
* other files. Note that a non-empty result increases the likelihood of false positives
305+
* from `getSemanticDiagnostics`.
306+
*
307+
* While these represent the majority of syntax-related diagnostics, there are some
308+
* that require the type system, which will be present in `getSemanticDiagnostics`.
309+
*
310+
* @param fileName A path to the file you want syntactic diagnostics for
311+
*/
294312
getSyntacticDiagnostics(fileName: string): DiagnosticWithLocation[];
295-
/** The first time this is called, it will return global diagnostics (no location). */
313+
314+
/**
315+
* Gets warnings or errors indicating type system issues in a given file.
316+
* Requesting semantic diagnostics may start up the type system and
317+
* run deferred work, so the first call may take longer than subsequent calls.
318+
*
319+
* Unlike the other get*Diagnostics functions, these diagnostics can potentially not
320+
* include a reference to a source file. Specifically, the first time this is called,
321+
* it will return global diagnostics with no associated location.
322+
*
323+
* To contrast the differences between semantic and syntactic diagnostics, consider the
324+
* sentence: "The sun is green." is syntactically correct; those are real English words with
325+
* correct sentence structure. However, it is semantically invalid, because it is not true.
326+
*
327+
* @param fileName A path to the file you want semantic diagnostics for
328+
*/
296329
getSemanticDiagnostics(fileName: string): Diagnostic[];
330+
331+
/**
332+
* Gets suggestion diagnostics for a specific file. These diagnostics tend to
333+
* proactively suggest refactors, as opposed to diagnostics that indicate
334+
* potentially incorrect runtime behavior.
335+
*
336+
* @param fileName A path to the file you want semantic diagnostics for
337+
*/
297338
getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[];
298339

299340
// TODO: Rename this to getProgramDiagnostics to better indicate that these are any
300341
// diagnostics present for the program level, and not just 'options' diagnostics.
301-
getCompilerOptionsDiagnostics(): Diagnostic[];
302342

303343
/**
304-
* @deprecated Use getEncodedSyntacticClassifications instead.
344+
* Gets global diagnostics related to the program configuration and compiler options.
305345
*/
346+
getCompilerOptionsDiagnostics(): Diagnostic[];
347+
348+
/** @deprecated Use getEncodedSyntacticClassifications instead. */
306349
getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
307350

308-
/**
309-
* @deprecated Use getEncodedSemanticClassifications instead.
310-
*/
351+
/** @deprecated Use getEncodedSemanticClassifications instead. */
311352
getSemanticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
312353

313354
// Encoded as triples of [start, length, ClassificationType].
314355
getEncodedSyntacticClassifications(fileName: string, span: TextSpan): Classifications;
315356
getEncodedSemanticClassifications(fileName: string, span: TextSpan): Classifications;
316357

358+
/**
359+
* Gets completion entries at a particular position in a file.
360+
*
361+
* @param fileName The path to the file
362+
* @param position A zero-based index of the character where you want the entries
363+
* @param options An object describing how the request was triggered and what kinds
364+
* of code actions can be returned with the completions.
365+
*/
317366
getCompletionsAtPosition(fileName: string, position: number, options: GetCompletionsAtPositionOptions | undefined): WithMetadata<CompletionInfo> | undefined;
318-
// "options" and "source" are optional only for backwards-compatibility
367+
368+
/**
369+
* Gets the extended details for a completion entry retrieved from `getCompletionsAtPosition`.
370+
*
371+
* @param fileName The path to the file
372+
* @param position A zero based index of the character where you want the entries
373+
* @param entryName The name from an existing completion which came from `getCompletionsAtPosition`
374+
* @param formatOptions How should code samples in the completions be formatted, can be undefined for backwards compatibility
375+
* @param source Source code for the current file, can be undefined for backwards compatibility
376+
* @param preferences User settings, can be undefined for backwards compatibility
377+
*/
319378
getCompletionEntryDetails(
320379
fileName: string,
321380
position: number,
322-
name: string,
381+
entryName: string,
323382
formatOptions: FormatCodeOptions | FormatCodeSettings | undefined,
324383
source: string | undefined,
325384
preferences: UserPreferences | undefined,
326385
): CompletionEntryDetails | undefined;
386+
327387
getCompletionEntrySymbol(fileName: string, position: number, name: string, source: string | undefined): Symbol | undefined;
328388

389+
/**
390+
* Gets semantic information about the identifier at a particular position in a
391+
* file. Quick info is what you typically see when you hover in an editor.
392+
*
393+
* @param fileName The path to the file
394+
* @param position A zero-based index of the character where you want the quick info
395+
*/
329396
getQuickInfoAtPosition(fileName: string, position: number): QuickInfo | undefined;
330397

331398
getNameOrDottedNameSpan(fileName: string, startPos: number, endPos: number): TextSpan | undefined;

‎tests/baselines/reference/api/tsserverlibrary.d.ts‎

Lines changed: 70 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5139,25 +5139,88 @@ declare namespace ts {
51395139
metadata?: unknown;
51405140
};
51415141
interface LanguageService {
5142+
/** This is used as a part of restarting the language service. */
51425143
cleanupSemanticCache(): void;
5144+
/**
5145+
* Gets errors indicating invalid syntax in a file.
5146+
*
5147+
* In English, "this cdeo have, erorrs" is syntactically invalid because it has typos,
5148+
* grammatical errors, and misplaced punctuation. Likewise, examples of syntax
5149+
* errors in TypeScript are missing parentheses in an `if` statement, mismatched
5150+
* curly braces, and using a reserved keyword as a variable name.
5151+
*
5152+
* These diagnostics are inexpensive to compute and don't require knowledge of
5153+
* other files. Note that a non-empty result increases the likelihood of false positives
5154+
* from `getSemanticDiagnostics`.
5155+
*
5156+
* While these represent the majority of syntax-related diagnostics, there are some
5157+
* that require the type system, which will be present in `getSemanticDiagnostics`.
5158+
*
5159+
* @param fileName A path to the file you want syntactic diagnostics for
5160+
*/
51435161
getSyntacticDiagnostics(fileName: string): DiagnosticWithLocation[];
5144-
/** The first time this is called, it will return global diagnostics (no location). */
5162+
/**
5163+
* Gets warnings or errors indicating type system issues in a given file.
5164+
* Requesting semantic diagnostics may start up the type system and
5165+
* run deferred work, so the first call may take longer than subsequent calls.
5166+
*
5167+
* Unlike the other get*Diagnostics functions, these diagnostics can potentially not
5168+
* include a reference to a source file. Specifically, the first time this is called,
5169+
* it will return global diagnostics with no associated location.
5170+
*
5171+
* To contrast the differences between semantic and syntactic diagnostics, consider the
5172+
* sentence: "The sun is green." is syntactically correct; those are real English words with
5173+
* correct sentence structure. However, it is semantically invalid, because it is not true.
5174+
*
5175+
* @param fileName A path to the file you want semantic diagnostics for
5176+
*/
51455177
getSemanticDiagnostics(fileName: string): Diagnostic[];
5146-
getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[];
5147-
getCompilerOptionsDiagnostics(): Diagnostic[];
51485178
/**
5149-
* @deprecated Use getEncodedSyntacticClassifications instead.
5179+
* Gets suggestion diagnostics for a specific file. These diagnostics tend to
5180+
* proactively suggest refactors, as opposed to diagnostics that indicate
5181+
* potentially incorrect runtime behavior.
5182+
*
5183+
* @param fileName A path to the file you want semantic diagnostics for
51505184
*/
5151-
getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
5185+
getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[];
51525186
/**
5153-
* @deprecated Use getEncodedSemanticClassifications instead.
5187+
* Gets global diagnostics related to the program configuration and compiler options.
51545188
*/
5189+
getCompilerOptionsDiagnostics(): Diagnostic[];
5190+
/** @deprecated Use getEncodedSyntacticClassifications instead. */
5191+
getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
5192+
/** @deprecated Use getEncodedSemanticClassifications instead. */
51555193
getSemanticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
51565194
getEncodedSyntacticClassifications(fileName: string, span: TextSpan): Classifications;
51575195
getEncodedSemanticClassifications(fileName: string, span: TextSpan): Classifications;
5196+
/**
5197+
* Gets completion entries at a particular position in a file.
5198+
*
5199+
* @param fileName The path to the file
5200+
* @param position A zero-based index of the character where you want the entries
5201+
* @param options An object describing how the request was triggered and what kinds
5202+
* of code actions can be returned with the completions.
5203+
*/
51585204
getCompletionsAtPosition(fileName: string, position: number, options: GetCompletionsAtPositionOptions | undefined): WithMetadata<CompletionInfo> | undefined;
5159-
getCompletionEntryDetails(fileName: string, position: number, name: string, formatOptions: FormatCodeOptions | FormatCodeSettings | undefined, source: string | undefined, preferences: UserPreferences | undefined): CompletionEntryDetails | undefined;
5205+
/**
5206+
* Gets the extended details for a completion entry retrieved from `getCompletionsAtPosition`.
5207+
*
5208+
* @param fileName The path to the file
5209+
* @param position A zero based index of the character where you want the entries
5210+
* @param entryName The name from an existing completion which came from `getCompletionsAtPosition`
5211+
* @param formatOptions How should code samples in the completions be formatted, can be undefined for backwards compatibility
5212+
* @param source Source code for the current file, can be undefined for backwards compatibility
5213+
* @param preferences User settings, can be undefined for backwards compatibility
5214+
*/
5215+
getCompletionEntryDetails(fileName: string, position: number, entryName: string, formatOptions: FormatCodeOptions | FormatCodeSettings | undefined, source: string | undefined, preferences: UserPreferences | undefined): CompletionEntryDetails | undefined;
51605216
getCompletionEntrySymbol(fileName: string, position: number, name: string, source: string | undefined): Symbol | undefined;
5217+
/**
5218+
* Gets semantic information about the identifier at a particular position in a
5219+
* file. Quick info is what you typically see when you hover in an editor.
5220+
*
5221+
* @param fileName The path to the file
5222+
* @param position A zero-based index of the character where you want the quick info
5223+
*/
51615224
getQuickInfoAtPosition(fileName: string, position: number): QuickInfo | undefined;
51625225
getNameOrDottedNameSpan(fileName: string, startPos: number, endPos: number): TextSpan | undefined;
51635226
getBreakpointStatementAtPosition(fileName: string, position: number): TextSpan | undefined;

‎tests/baselines/reference/api/typescript.d.ts‎

Lines changed: 70 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -5139,25 +5139,88 @@ declare namespace ts {
51395139
metadata?: unknown;
51405140
};
51415141
interface LanguageService {
5142+
/** This is used as a part of restarting the language service. */
51425143
cleanupSemanticCache(): void;
5144+
/**
5145+
* Gets errors indicating invalid syntax in a file.
5146+
*
5147+
* In English, "this cdeo have, erorrs" is syntactically invalid because it has typos,
5148+
* grammatical errors, and misplaced punctuation. Likewise, examples of syntax
5149+
* errors in TypeScript are missing parentheses in an `if` statement, mismatched
5150+
* curly braces, and using a reserved keyword as a variable name.
5151+
*
5152+
* These diagnostics are inexpensive to compute and don't require knowledge of
5153+
* other files. Note that a non-empty result increases the likelihood of false positives
5154+
* from `getSemanticDiagnostics`.
5155+
*
5156+
* While these represent the majority of syntax-related diagnostics, there are some
5157+
* that require the type system, which will be present in `getSemanticDiagnostics`.
5158+
*
5159+
* @param fileName A path to the file you want syntactic diagnostics for
5160+
*/
51435161
getSyntacticDiagnostics(fileName: string): DiagnosticWithLocation[];
5144-
/** The first time this is called, it will return global diagnostics (no location). */
5162+
/**
5163+
* Gets warnings or errors indicating type system issues in a given file.
5164+
* Requesting semantic diagnostics may start up the type system and
5165+
* run deferred work, so the first call may take longer than subsequent calls.
5166+
*
5167+
* Unlike the other get*Diagnostics functions, these diagnostics can potentially not
5168+
* include a reference to a source file. Specifically, the first time this is called,
5169+
* it will return global diagnostics with no associated location.
5170+
*
5171+
* To contrast the differences between semantic and syntactic diagnostics, consider the
5172+
* sentence: "The sun is green." is syntactically correct; those are real English words with
5173+
* correct sentence structure. However, it is semantically invalid, because it is not true.
5174+
*
5175+
* @param fileName A path to the file you want semantic diagnostics for
5176+
*/
51455177
getSemanticDiagnostics(fileName: string): Diagnostic[];
5146-
getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[];
5147-
getCompilerOptionsDiagnostics(): Diagnostic[];
51485178
/**
5149-
* @deprecated Use getEncodedSyntacticClassifications instead.
5179+
* Gets suggestion diagnostics for a specific file. These diagnostics tend to
5180+
* proactively suggest refactors, as opposed to diagnostics that indicate
5181+
* potentially incorrect runtime behavior.
5182+
*
5183+
* @param fileName A path to the file you want semantic diagnostics for
51505184
*/
5151-
getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
5185+
getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[];
51525186
/**
5153-
* @deprecated Use getEncodedSemanticClassifications instead.
5187+
* Gets global diagnostics related to the program configuration and compiler options.
51545188
*/
5189+
getCompilerOptionsDiagnostics(): Diagnostic[];
5190+
/** @deprecated Use getEncodedSyntacticClassifications instead. */
5191+
getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
5192+
/** @deprecated Use getEncodedSemanticClassifications instead. */
51555193
getSemanticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
51565194
getEncodedSyntacticClassifications(fileName: string, span: TextSpan): Classifications;
51575195
getEncodedSemanticClassifications(fileName: string, span: TextSpan): Classifications;
5196+
/**
5197+
* Gets completion entries at a particular position in a file.
5198+
*
5199+
* @param fileName The path to the file
5200+
* @param position A zero-based index of the character where you want the entries
5201+
* @param options An object describing how the request was triggered and what kinds
5202+
* of code actions can be returned with the completions.
5203+
*/
51585204
getCompletionsAtPosition(fileName: string, position: number, options: GetCompletionsAtPositionOptions | undefined): WithMetadata<CompletionInfo> | undefined;
5159-
getCompletionEntryDetails(fileName: string, position: number, name: string, formatOptions: FormatCodeOptions | FormatCodeSettings | undefined, source: string | undefined, preferences: UserPreferences | undefined): CompletionEntryDetails | undefined;
5205+
/**
5206+
* Gets the extended details for a completion entry retrieved from `getCompletionsAtPosition`.
5207+
*
5208+
* @param fileName The path to the file
5209+
* @param position A zero based index of the character where you want the entries
5210+
* @param entryName The name from an existing completion which came from `getCompletionsAtPosition`
5211+
* @param formatOptions How should code samples in the completions be formatted, can be undefined for backwards compatibility
5212+
* @param source Source code for the current file, can be undefined for backwards compatibility
5213+
* @param preferences User settings, can be undefined for backwards compatibility
5214+
*/
5215+
getCompletionEntryDetails(fileName: string, position: number, entryName: string, formatOptions: FormatCodeOptions | FormatCodeSettings | undefined, source: string | undefined, preferences: UserPreferences | undefined): CompletionEntryDetails | undefined;
51605216
getCompletionEntrySymbol(fileName: string, position: number, name: string, source: string | undefined): Symbol | undefined;
5217+
/**
5218+
* Gets semantic information about the identifier at a particular position in a
5219+
* file. Quick info is what you typically see when you hover in an editor.
5220+
*
5221+
* @param fileName The path to the file
5222+
* @param position A zero-based index of the character where you want the quick info
5223+
*/
51615224
getQuickInfoAtPosition(fileName: string, position: number): QuickInfo | undefined;
51625225
getNameOrDottedNameSpan(fileName: string, startPos: number, endPos: number): TextSpan | undefined;
51635226
getBreakpointStatementAtPosition(fileName: string, position: number): TextSpan | undefined;

0 commit comments

Comments
 (0)