From f1cc8e4e4e191ac6fac6086ba1a0a1541abc64c9 Mon Sep 17 00:00:00 2001 From: Orta Date: Fri, 13 Mar 2020 13:26:39 -0400 Subject: [PATCH] [minor] Adds some docs to the LSP interface (#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 * Remove the getCompilerOptionsDiagnostics -> getProgramDiagnostics change Co-authored-by: Andrew Branch --- src/harness/harnessLanguageService.ts | 1 - src/services/types.ts | 85 +++++++++++++++++-- .../reference/api/tsserverlibrary.d.ts | 79 +++++++++++++++-- tests/baselines/reference/api/typescript.d.ts | 79 +++++++++++++++-- 4 files changed, 218 insertions(+), 26 deletions(-) diff --git a/src/harness/harnessLanguageService.ts b/src/harness/harnessLanguageService.ts index 23093406e2d..fbaf9ba545d 100644 --- a/src/harness/harnessLanguageService.ts +++ b/src/harness/harnessLanguageService.ts @@ -520,7 +520,6 @@ namespace Harness.LanguageService { getNavigationTree(fileName: string): ts.NavigationTree { return unwrapJSONCallResult(this.shim.getNavigationTree(fileName)); } - getOutliningSpans(fileName: string): ts.OutliningSpan[] { return unwrapJSONCallResult(this.shim.getOutliningSpans(fileName)); } diff --git a/src/services/types.ts b/src/services/types.ts index 6cb884a08ea..fb7e0cb8d35 100644 --- a/src/services/types.ts +++ b/src/services/types.ts @@ -289,43 +289,110 @@ namespace ts { // with a language service host instance // export interface LanguageService { + /** This is used as a part of restarting the language service. */ cleanupSemanticCache(): void; + /** + * Gets errors indicating invalid syntax in a file. + * + * In English, "this cdeo have, erorrs" is syntactically invalid because it has typos, + * grammatical errors, and misplaced punctuation. Likewise, examples of syntax + * errors in TypeScript are missing parentheses in an `if` statement, mismatched + * curly braces, and using a reserved keyword as a variable name. + * + * These diagnostics are inexpensive to compute and don't require knowledge of + * other files. Note that a non-empty result increases the likelihood of false positives + * from `getSemanticDiagnostics`. + * + * While these represent the majority of syntax-related diagnostics, there are some + * that require the type system, which will be present in `getSemanticDiagnostics`. + * + * @param fileName A path to the file you want syntactic diagnostics for + */ getSyntacticDiagnostics(fileName: string): DiagnosticWithLocation[]; - /** The first time this is called, it will return global diagnostics (no location). */ + + /** + * Gets warnings or errors indicating type system issues in a given file. + * Requesting semantic diagnostics may start up the type system and + * run deferred work, so the first call may take longer than subsequent calls. + * + * Unlike the other get*Diagnostics functions, these diagnostics can potentially not + * include a reference to a source file. Specifically, the first time this is called, + * it will return global diagnostics with no associated location. + * + * To contrast the differences between semantic and syntactic diagnostics, consider the + * sentence: "The sun is green." is syntactically correct; those are real English words with + * correct sentence structure. However, it is semantically invalid, because it is not true. + * + * @param fileName A path to the file you want semantic diagnostics for + */ getSemanticDiagnostics(fileName: string): Diagnostic[]; + + /** + * Gets suggestion diagnostics for a specific file. These diagnostics tend to + * proactively suggest refactors, as opposed to diagnostics that indicate + * potentially incorrect runtime behavior. + * + * @param fileName A path to the file you want semantic diagnostics for + */ getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[]; // TODO: Rename this to getProgramDiagnostics to better indicate that these are any // diagnostics present for the program level, and not just 'options' diagnostics. + + /** + * Gets global diagnostics related to the program configuration and compiler options. + */ getCompilerOptionsDiagnostics(): Diagnostic[]; - /** - * @deprecated Use getEncodedSyntacticClassifications instead. - */ + /** @deprecated Use getEncodedSyntacticClassifications instead. */ getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[]; - /** - * @deprecated Use getEncodedSemanticClassifications instead. - */ + /** @deprecated Use getEncodedSemanticClassifications instead. */ getSemanticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[]; // Encoded as triples of [start, length, ClassificationType]. getEncodedSyntacticClassifications(fileName: string, span: TextSpan): Classifications; getEncodedSemanticClassifications(fileName: string, span: TextSpan): Classifications; + /** + * Gets completion entries at a particular position in a file. + * + * @param fileName The path to the file + * @param position A zero-based index of the character where you want the entries + * @param options An object describing how the request was triggered and what kinds + * of code actions can be returned with the completions. + */ getCompletionsAtPosition(fileName: string, position: number, options: GetCompletionsAtPositionOptions | undefined): WithMetadata | undefined; - // "options" and "source" are optional only for backwards-compatibility + + /** + * Gets the extended details for a completion entry retrieved from `getCompletionsAtPosition`. + * + * @param fileName The path to the file + * @param position A zero based index of the character where you want the entries + * @param entryName The name from an existing completion which came from `getCompletionsAtPosition` + * @param formatOptions How should code samples in the completions be formatted, can be undefined for backwards compatibility + * @param source Source code for the current file, can be undefined for backwards compatibility + * @param preferences User settings, can be undefined for backwards compatibility + */ getCompletionEntryDetails( fileName: string, position: number, - name: string, + entryName: string, formatOptions: FormatCodeOptions | FormatCodeSettings | undefined, source: string | undefined, preferences: UserPreferences | undefined, ): CompletionEntryDetails | undefined; + getCompletionEntrySymbol(fileName: string, position: number, name: string, source: string | undefined): Symbol | undefined; + /** + * Gets semantic information about the identifier at a particular position in a + * file. Quick info is what you typically see when you hover in an editor. + * + * @param fileName The path to the file + * @param position A zero-based index of the character where you want the quick info + */ getQuickInfoAtPosition(fileName: string, position: number): QuickInfo | undefined; getNameOrDottedNameSpan(fileName: string, startPos: number, endPos: number): TextSpan | undefined; diff --git a/tests/baselines/reference/api/tsserverlibrary.d.ts b/tests/baselines/reference/api/tsserverlibrary.d.ts index ed8fa7b16ca..253348646a7 100644 --- a/tests/baselines/reference/api/tsserverlibrary.d.ts +++ b/tests/baselines/reference/api/tsserverlibrary.d.ts @@ -5139,25 +5139,88 @@ declare namespace ts { metadata?: unknown; }; interface LanguageService { + /** This is used as a part of restarting the language service. */ cleanupSemanticCache(): void; + /** + * Gets errors indicating invalid syntax in a file. + * + * In English, "this cdeo have, erorrs" is syntactically invalid because it has typos, + * grammatical errors, and misplaced punctuation. Likewise, examples of syntax + * errors in TypeScript are missing parentheses in an `if` statement, mismatched + * curly braces, and using a reserved keyword as a variable name. + * + * These diagnostics are inexpensive to compute and don't require knowledge of + * other files. Note that a non-empty result increases the likelihood of false positives + * from `getSemanticDiagnostics`. + * + * While these represent the majority of syntax-related diagnostics, there are some + * that require the type system, which will be present in `getSemanticDiagnostics`. + * + * @param fileName A path to the file you want syntactic diagnostics for + */ getSyntacticDiagnostics(fileName: string): DiagnosticWithLocation[]; - /** The first time this is called, it will return global diagnostics (no location). */ + /** + * Gets warnings or errors indicating type system issues in a given file. + * Requesting semantic diagnostics may start up the type system and + * run deferred work, so the first call may take longer than subsequent calls. + * + * Unlike the other get*Diagnostics functions, these diagnostics can potentially not + * include a reference to a source file. Specifically, the first time this is called, + * it will return global diagnostics with no associated location. + * + * To contrast the differences between semantic and syntactic diagnostics, consider the + * sentence: "The sun is green." is syntactically correct; those are real English words with + * correct sentence structure. However, it is semantically invalid, because it is not true. + * + * @param fileName A path to the file you want semantic diagnostics for + */ getSemanticDiagnostics(fileName: string): Diagnostic[]; + /** + * Gets suggestion diagnostics for a specific file. These diagnostics tend to + * proactively suggest refactors, as opposed to diagnostics that indicate + * potentially incorrect runtime behavior. + * + * @param fileName A path to the file you want semantic diagnostics for + */ getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[]; + /** + * Gets global diagnostics related to the program configuration and compiler options. + */ getCompilerOptionsDiagnostics(): Diagnostic[]; - /** - * @deprecated Use getEncodedSyntacticClassifications instead. - */ + /** @deprecated Use getEncodedSyntacticClassifications instead. */ getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[]; - /** - * @deprecated Use getEncodedSemanticClassifications instead. - */ + /** @deprecated Use getEncodedSemanticClassifications instead. */ getSemanticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[]; getEncodedSyntacticClassifications(fileName: string, span: TextSpan): Classifications; getEncodedSemanticClassifications(fileName: string, span: TextSpan): Classifications; + /** + * Gets completion entries at a particular position in a file. + * + * @param fileName The path to the file + * @param position A zero-based index of the character where you want the entries + * @param options An object describing how the request was triggered and what kinds + * of code actions can be returned with the completions. + */ getCompletionsAtPosition(fileName: string, position: number, options: GetCompletionsAtPositionOptions | undefined): WithMetadata | undefined; - getCompletionEntryDetails(fileName: string, position: number, name: string, formatOptions: FormatCodeOptions | FormatCodeSettings | undefined, source: string | undefined, preferences: UserPreferences | undefined): CompletionEntryDetails | undefined; + /** + * Gets the extended details for a completion entry retrieved from `getCompletionsAtPosition`. + * + * @param fileName The path to the file + * @param position A zero based index of the character where you want the entries + * @param entryName The name from an existing completion which came from `getCompletionsAtPosition` + * @param formatOptions How should code samples in the completions be formatted, can be undefined for backwards compatibility + * @param source Source code for the current file, can be undefined for backwards compatibility + * @param preferences User settings, can be undefined for backwards compatibility + */ + getCompletionEntryDetails(fileName: string, position: number, entryName: string, formatOptions: FormatCodeOptions | FormatCodeSettings | undefined, source: string | undefined, preferences: UserPreferences | undefined): CompletionEntryDetails | undefined; getCompletionEntrySymbol(fileName: string, position: number, name: string, source: string | undefined): Symbol | undefined; + /** + * Gets semantic information about the identifier at a particular position in a + * file. Quick info is what you typically see when you hover in an editor. + * + * @param fileName The path to the file + * @param position A zero-based index of the character where you want the quick info + */ getQuickInfoAtPosition(fileName: string, position: number): QuickInfo | undefined; getNameOrDottedNameSpan(fileName: string, startPos: number, endPos: number): TextSpan | undefined; getBreakpointStatementAtPosition(fileName: string, position: number): TextSpan | undefined; diff --git a/tests/baselines/reference/api/typescript.d.ts b/tests/baselines/reference/api/typescript.d.ts index 60b95aba83a..afd99ad98f6 100644 --- a/tests/baselines/reference/api/typescript.d.ts +++ b/tests/baselines/reference/api/typescript.d.ts @@ -5139,25 +5139,88 @@ declare namespace ts { metadata?: unknown; }; interface LanguageService { + /** This is used as a part of restarting the language service. */ cleanupSemanticCache(): void; + /** + * Gets errors indicating invalid syntax in a file. + * + * In English, "this cdeo have, erorrs" is syntactically invalid because it has typos, + * grammatical errors, and misplaced punctuation. Likewise, examples of syntax + * errors in TypeScript are missing parentheses in an `if` statement, mismatched + * curly braces, and using a reserved keyword as a variable name. + * + * These diagnostics are inexpensive to compute and don't require knowledge of + * other files. Note that a non-empty result increases the likelihood of false positives + * from `getSemanticDiagnostics`. + * + * While these represent the majority of syntax-related diagnostics, there are some + * that require the type system, which will be present in `getSemanticDiagnostics`. + * + * @param fileName A path to the file you want syntactic diagnostics for + */ getSyntacticDiagnostics(fileName: string): DiagnosticWithLocation[]; - /** The first time this is called, it will return global diagnostics (no location). */ + /** + * Gets warnings or errors indicating type system issues in a given file. + * Requesting semantic diagnostics may start up the type system and + * run deferred work, so the first call may take longer than subsequent calls. + * + * Unlike the other get*Diagnostics functions, these diagnostics can potentially not + * include a reference to a source file. Specifically, the first time this is called, + * it will return global diagnostics with no associated location. + * + * To contrast the differences between semantic and syntactic diagnostics, consider the + * sentence: "The sun is green." is syntactically correct; those are real English words with + * correct sentence structure. However, it is semantically invalid, because it is not true. + * + * @param fileName A path to the file you want semantic diagnostics for + */ getSemanticDiagnostics(fileName: string): Diagnostic[]; + /** + * Gets suggestion diagnostics for a specific file. These diagnostics tend to + * proactively suggest refactors, as opposed to diagnostics that indicate + * potentially incorrect runtime behavior. + * + * @param fileName A path to the file you want semantic diagnostics for + */ getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[]; + /** + * Gets global diagnostics related to the program configuration and compiler options. + */ getCompilerOptionsDiagnostics(): Diagnostic[]; - /** - * @deprecated Use getEncodedSyntacticClassifications instead. - */ + /** @deprecated Use getEncodedSyntacticClassifications instead. */ getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[]; - /** - * @deprecated Use getEncodedSemanticClassifications instead. - */ + /** @deprecated Use getEncodedSemanticClassifications instead. */ getSemanticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[]; getEncodedSyntacticClassifications(fileName: string, span: TextSpan): Classifications; getEncodedSemanticClassifications(fileName: string, span: TextSpan): Classifications; + /** + * Gets completion entries at a particular position in a file. + * + * @param fileName The path to the file + * @param position A zero-based index of the character where you want the entries + * @param options An object describing how the request was triggered and what kinds + * of code actions can be returned with the completions. + */ getCompletionsAtPosition(fileName: string, position: number, options: GetCompletionsAtPositionOptions | undefined): WithMetadata | undefined; - getCompletionEntryDetails(fileName: string, position: number, name: string, formatOptions: FormatCodeOptions | FormatCodeSettings | undefined, source: string | undefined, preferences: UserPreferences | undefined): CompletionEntryDetails | undefined; + /** + * Gets the extended details for a completion entry retrieved from `getCompletionsAtPosition`. + * + * @param fileName The path to the file + * @param position A zero based index of the character where you want the entries + * @param entryName The name from an existing completion which came from `getCompletionsAtPosition` + * @param formatOptions How should code samples in the completions be formatted, can be undefined for backwards compatibility + * @param source Source code for the current file, can be undefined for backwards compatibility + * @param preferences User settings, can be undefined for backwards compatibility + */ + getCompletionEntryDetails(fileName: string, position: number, entryName: string, formatOptions: FormatCodeOptions | FormatCodeSettings | undefined, source: string | undefined, preferences: UserPreferences | undefined): CompletionEntryDetails | undefined; getCompletionEntrySymbol(fileName: string, position: number, name: string, source: string | undefined): Symbol | undefined; + /** + * Gets semantic information about the identifier at a particular position in a + * file. Quick info is what you typically see when you hover in an editor. + * + * @param fileName The path to the file + * @param position A zero-based index of the character where you want the quick info + */ getQuickInfoAtPosition(fileName: string, position: number): QuickInfo | undefined; getNameOrDottedNameSpan(fileName: string, startPos: number, endPos: number): TextSpan | undefined; getBreakpointStatementAtPosition(fileName: string, position: number): TextSpan | undefined;