Adds some docs to the LSP dts

Author: orta

src/services/services.ts

@@ -1452,6 +1452,12 @@ namespace ts {
             return computeSuggestionDiagnostics(getValidSourceFile(fileName), program, cancellationToken);
         }
 
+        // @ts-ignore - 'getProgramDiagnostics' is declared but its value is never read - this is because it is a dupe of getCompilerOptionsDiagnostics
+        // so that the external interface makes more sense.
+        function getProgramDiagnostics() {
+            return getCompilerOptionsDiagnostics();
+        }
+
         function getCompilerOptionsDiagnostics() {
             synchronizeHostData();
             return [...program.getOptionsDiagnostics(cancellationToken), ...program.getGlobalDiagnostics(cancellationToken)];
@@ -2178,6 +2184,7 @@ namespace ts {
             getSyntacticDiagnostics,
             getSemanticDiagnostics,
             getSuggestionDiagnostics,
+            getProgramDiagnostics: getCompilerOptionsDiagnostics,
             getCompilerOptionsDiagnostics,
             getSyntacticClassifications,
             getSemanticClassifications,

src/services/types.ts

@@ -289,43 +289,108 @@ namespace ts {
     // with a language service host instance
     //
     export interface LanguageService {
+        /** This is used as a part of restarting the language server */
         cleanupSemanticCache(): void;
 
+        /**
+         * Gets warnings or errors indicating invalid syntax in a given file.
+         * 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 diagnostics
+         * which require the type-system, and those will be available via getSemanticDiagnostics.
+         *
+         * To contrast with English, this cdeo has erorrs." is not syntactically correct because
+         * it has typoes, even though you can squint to understand.
+         *
+         * @param fileName A path to the file you want semantic diagnostics for
+         */
         getSyntacticDiagnostics(fileName: string): DiagnosticWithLocation[];
-        /** The first time this is called, it will return global diagnostics (no location). */
-        getSemanticDiagnostics(fileName: string): Diagnostic[];
-        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.
-        getCompilerOptionsDiagnostics(): Diagnostic[];
+        /**
+         * 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 time you make this call it 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 all real words
+         * in english. 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[];
 
         /**
-         * @deprecated Use getEncodedSyntacticClassifications instead.
+         * Get suggestion diagnostics for a specific files. These suggestions tend
+         * to be proactive codefixes and refactors, as opposed to issues which require
+         * fixing in order for the to be correct.
+         *
+         * @param fileName A path to the file you want semantic diagnostics for
          */
-        getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
+        getSuggestionDiagnostics(fileName: string): DiagnosticWithLocation[];
 
         /**
-         * @deprecated Use getEncodedSemanticClassifications instead.
+         * Gets diagnostics related the current program, these tend to be about the compiler
+         * options for a project.
          */
+        getProgramDiagnostics(): Diagnostic[];
+
+        /**  @deprecated Use getProgramDiagnostics instead. */
+        getCompilerOptionsDiagnostics(): Diagnostic[];
+
+        /** @deprecated Use getEncodedSyntacticClassifications instead. */
+        getSyntacticClassifications(fileName: string, span: TextSpan): ClassifiedSpan[];
+
+        /** @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;
 
+        /**
+         * Get the completion entries at a particular cursor
+         *
+         * @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 completions were triggered, can be undefined for backwards compatibility
+         */
         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
+         *
+         * @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;