[analysis_server] Allow documentation preferences to be different between completion/hovers

For Dart-Code/Dart-Code#4729 we added a configuration setting to let you control how much documentation was included in responses. The motivation here was to reduce the completion payload sizes when running in remote workspaces (Dart-Code would adjust the default setting if not explicitly set by the user based on the workspace kind).

However in hindsight, forcing no docs on Hovers just because we didn't want them in Completion requests was a bad choice, because these are individual requests where the payload size is less important and seeing the docs is useful.

So this alters the setting to accept a `Map` to allow you to have different preferences for each request that returns docs. Dart-Code will be updated to adjust the defaults accordingly (after this lands) so that Hover/SignatureHelp can default to `"full"` even in remote workspaces.

Work towards Dart-Code/Dart-Code#5499

Change-Id: Ib64f762a0559c7afc7653fad9749fc208beee8b3
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/431280
Reviewed-by: Samuel Rawlins <[email protected]>
Reviewed-by: Brian Wilkerson <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>

Author: DanTup

pkg/analysis_server/lib/src/lsp/client_configuration.dart

@@ -210,8 +210,8 @@ class LspGlobalClientConfiguration extends LspResourceClientConfiguration {
   bool get includeDependenciesInWorkspaceSymbols =>
       _settings['includeDependenciesInWorkspaceSymbols'] as bool? ?? true;
 
-  /// The users preferred kind of documentation for Hovers, Code Completion and
-  /// other related panels in the UI.
+  /// The users preferred kind of documentation for requests that return many
+  /// results and could have large payloads when docs are included.
   ///
   /// If the user has not expressed a preference, defaults to
   /// [DocumentationPreference.full].
@@ -235,7 +235,7 @@ class LspGlobalClientConfiguration extends LspResourceClientConfiguration {
   bool get showAllTodos =>
       _settings['showTodos'] is bool ? _settings['showTodos'] as bool : false;
 
-  // A specific set of `TODO` comments that should generate diagnostics.
+  /// A specific set of `TODO` comments that should generate diagnostics.
   ///
   /// Codes are all forced UPPERCASE regardless of what the client supplies.
   ///

pkg/analysis_server/lib/src/lsp/handlers/handler_hover.dart

@@ -123,8 +123,6 @@ class HoverHandler
       server.getDartdocDirectiveInfoFor(unit),
       compilationUnit,
       offset,
-      documentationPreference:
-          server.lspClientConfiguration.global.preferredDocumentation,
     );
     var hover = computer.compute();
     return success(toHover(clientCapabilities, unit.lineInfo, hover));

pkg/analysis_server/lib/src/lsp/handlers/handler_signature_help.dart

@@ -78,13 +78,7 @@ class SignatureHelpHandler
         return success(typeArgsSignature);
       }
 
-      var computer = DartUnitSignatureComputer(
-        dartDocInfo,
-        unit.unit,
-        offset,
-        documentationPreference:
-            server.lspClientConfiguration.global.preferredDocumentation,
-      );
+      var computer = DartUnitSignatureComputer(dartDocInfo, unit.unit, offset);
       if (!computer.offsetIsValid) {
         return success(null); // No error, just no valid hover.
       }
@@ -122,8 +116,6 @@ class SignatureHelpHandler
       unit,
       offset,
       formats,
-      documentationPreference:
-          server.lspClientConfiguration.global.preferredDocumentation,
     );
     if (!typeArgsComputer.offsetIsValid) {
       return null;

pkg/analysis_server/test/lsp/hover_test.dart

@@ -151,13 +151,12 @@ class HoverTest extends AbstractLspAnalysisServerTest {
   Future<void> test_dartDocPreference_full() =>
       assertDocumentation('full', includesSummary: true, includesFull: true);
 
-  Future<void> test_dartDocPreference_none() =>
-      assertDocumentation('none', includesSummary: false, includesFull: false);
-
   Future<void> test_dartDocPreference_summary() => assertDocumentation(
     'summary',
     includesSummary: true,
-    includesFull: false,
+    // Doc preferences don't apply to single-result requests so always expect
+    // full docs.
+    includesFull: true,
   );
 
   /// No preference should result in full docs.

pkg/analysis_server/test/lsp/signature_help_test.dart

@@ -429,16 +429,12 @@ foo(String s, int i) {
     includesFull: true,
   );
 
-  Future<void> test_dartDocPreference_none() => assertArgsDocumentation(
-    'none',
-    includesSummary: false,
-    includesFull: false,
-  );
-
   Future<void> test_dartDocPreference_summary() => assertArgsDocumentation(
     'summary',
     includesSummary: true,
-    includesFull: false,
+    // Doc preferences don't apply to single-result requests so always expect
+    // full docs.
+    includesFull: true,
   );
 
   /// No preference should result in full docs.
@@ -896,19 +892,14 @@ foo(String s, int i) {
         includesFull: true,
       );
 
-  Future<void> test_typeArgs_dartDocPreference_none() =>
-      assertArgsDocumentation(
-        'none',
-        includesSummary: false,
-        includesFull: false,
-      );
-
-  Future<void> test_typeArgs_dartDocPreference_summary() =>
-      assertArgsDocumentation(
-        'summary',
-        includesSummary: true,
-        includesFull: false,
-      );
+  Future<void>
+  test_typeArgs_dartDocPreference_summary() => assertArgsDocumentation(
+    'summary',
+    includesSummary: true,
+    // Doc preferences don't apply to single-result requests so always expect
+    // full docs.
+    includesFull: true,
+  );
 
   /// No preference should result in full docs.
   Future<void> test_typeArgs_dartDocPreference_unset() =>

pkg/analysis_server/tool/lsp_spec/README.md

@@ -42,7 +42,7 @@ Client workspace settings are requested with `workspace/configuration` during in
 - `dart.renameFilesWithClasses` (`String`): When set to `"always"`, will include edits to rename files when classes are renamed if the filename matches the class name (but in snake_form). When set to `"prompt"`, a prompt will be shown on each class rename asking to confirm the file rename. Otherwise, files will not be renamed. Renames are performed using LSP's ResourceOperation edits - that means the rename is simply included in the resulting `WorkspaceEdit` and must be handled by the client.
 - `dart.enableSnippets` (`bool?`): Whether to include code snippets (such as `class`, `stful`, `switch`) in code completion. When unspecified, snippets will be included.
 - `dart.updateImportsOnRename` (`bool?`): Whether to update imports and other directives when files are renamed. When unspecified, imports will be updated if the client supports `willRenameFiles` requests.
-- `dart.documentation` (`none`, `summary` or `full`): The typekind of dartdocs to include in Hovers, Code Completion, Signature Help and other similar requests. If not set, defaults to `full`.
+- `dart.documentation` (`none`, `summary`, `full`): The kind of dartdocs to include in requests that can return large numbers of results such as Code Completion. If not set, defaults to `full`.
 - `dart.includeDependenciesInWorkspaceSymbols` (`bool?`): Whether to include symbols from dependencies and Dart/Flutter SDKs in Workspace Symbol results. If not set, defaults to `true`.
 
 ## Method Status