maxmustermann/TypeScript
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

[minor] Adds some docs to the LSP interface (#36740)

Browse source 
* 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>
This commit is contained in:
Orta 2020-03-13 13:26:39 -04:00 committed by GitHub
parent eaeee9cc31
commit f1cc8e4e4e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 218 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
src/harness/harnessLanguageService.ts
View file

@ -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));
}

85
src/services/types.ts
View file

@ -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<CompletionInfo> | 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;

79
tests/baselines/reference/api/tsserverlibrary.d.ts vendored
View file

@ -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<CompletionInfo> | 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;

79
tests/baselines/reference/api/typescript.d.ts vendored
View file

@ -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<CompletionInfo> | 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;