[analysis_server] Split documentation out of hover computer

The hover computer had some logic in it that was reused elsewhere (like completion and signature help) and a TODO to move it out. While trying to migrate signature help I ended up trying to migrate the whole hover class which then led to other classes and got big. Hopefully splitting these up will make it easier to migrate them separately.

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

Author: DanTup

pkg/analysis_server/lib/src/computer/computer_documentation.dart

@@ -0,0 +1,105 @@
+// Copyright (c) 2024, the Dart project authors. Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+import 'package:analysis_server/src/computer/computer_overrides.dart';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:analyzer/src/dartdoc/dartdoc_directive_info.dart';
+
+/// Computes documentation for an [Element].
+class DartDocumentationComputer {
+  final DartdocDirectiveInfo dartdocInfo;
+
+  DartDocumentationComputer(this.dartdocInfo);
+
+  Documentation? compute(
+    Element elementBeingDocumented, {
+    bool includeSummary = false,
+  }) {
+    Element? element = elementBeingDocumented;
+    if (element is FieldFormalParameterElement) {
+      element = element.field;
+    }
+    if (element is ParameterElement) {
+      element = element.enclosingElement3;
+    }
+    if (element == null) {
+      // This can happen when the code is invalid, such as having a field formal
+      // parameter for a field that does not exist.
+      return null;
+    }
+
+    Element? documentedElement;
+    Element? documentedGetter;
+
+    // Look for documentation comments of overridden members
+    var overridden = findOverriddenElements(element);
+    var candidates = [
+      element,
+      ...overridden.superElements,
+      ...overridden.interfaceElements,
+      if (element case PropertyAccessorElement(variable2: var variable?))
+        variable
+    ];
+    for (var candidate in candidates) {
+      if (candidate.documentationComment != null) {
+        documentedElement = candidate;
+        break;
+      }
+      if (documentedGetter == null &&
+          candidate is PropertyAccessorElement &&
+          candidate.isSetter) {
+        var getter = candidate.correspondingGetter;
+        if (getter != null && getter.documentationComment != null) {
+          documentedGetter = getter;
+        }
+      }
+    }
+
+    // Use documentation of a corresponding getter if setters don't have it
+    documentedElement ??= documentedGetter;
+    if (documentedElement == null) {
+      return null;
+    }
+
+    var rawDoc = documentedElement.documentationComment;
+    if (rawDoc == null) {
+      return null;
+    }
+    var result =
+        dartdocInfo.processDartdoc(rawDoc, includeSummary: includeSummary);
+
+    var documentedElementClass = documentedElement.enclosingElement3;
+    if (documentedElementClass != null &&
+        documentedElementClass != element.enclosingElement3) {
+      var documentedClass = documentedElementClass.displayName;
+      result.full = '${result.full}\n\nCopied from `$documentedClass`.';
+    }
+
+    return result;
+  }
+
+  /// Compute documentation for [element] and return either the summary or full
+  /// docs (or `null`) depending on `preference`.
+  String? computePreferred(
+      Element element, DocumentationPreference preference) {
+    if (preference == DocumentationPreference.none) {
+      return null;
+    }
+
+    var doc = compute(
+      element,
+      includeSummary: preference == DocumentationPreference.summary,
+    );
+
+    return doc is DocumentationWithSummary ? doc.summary : doc?.full;
+  }
+}
+
+/// The type of documentation the user prefers to see in hovers and other
+/// related displays in their editor.
+enum DocumentationPreference {
+  none,
+  summary,
+  full,
+}

pkg/analysis_server/lib/src/computer/computer_hover.dart

@@ -4,7 +4,7 @@
 
 import 'package:analysis_server/protocol/protocol_generated.dart'
     show HoverInformation;
-import 'package:analysis_server/src/computer/computer_overrides.dart';
+import 'package:analysis_server/src/computer/computer_documentation.dart';
 import 'package:analyzer/dart/ast/ast.dart';
 import 'package:analyzer/dart/ast/syntactic_entity.dart';
 import 'package:analyzer/dart/element/element.dart';
@@ -21,17 +21,17 @@ typedef _OffsetLength = ({int offset, int length});
 /// A computer for the hover at the specified offset of a Dart
 /// [CompilationUnit].
 class DartUnitHoverComputer {
-  final DartdocDirectiveInfo _dartdocInfo;
   final CompilationUnit _unit;
   final int _offset;
   final DocumentationPreference documentationPreference;
+  final DartDocumentationComputer _documentationComputer;
 
   DartUnitHoverComputer(
-    this._dartdocInfo,
+    DartdocDirectiveInfo dartdocInfo,
     this._unit,
     this._offset, {
     this.documentationPreference = DocumentationPreference.full,
-  });
+  }) : _documentationComputer = DartDocumentationComputer(dartdocInfo);
 
   /// Returns the computed hover, maybe `null`.
   HoverInformation? compute() {
@@ -83,8 +83,8 @@ class DartUnitHoverComputer {
           hover.containingLibraryPath = libraryInfo?.libraryPath;
         }
         // documentation
-        hover.dartdoc = computePreferredDocumentation(
-            _dartdocInfo, element, documentationPreference);
+        hover.dartdoc = _documentationComputer.computePreferred(
+            element, documentationPreference);
       }
       // parameter
       hover.parameter = _parameterDisplayString(node);
@@ -272,94 +272,6 @@ class DartUnitHoverComputer {
             element.isSynthetic);
   }
 
-  static Documentation? computeDocumentation(
-      DartdocDirectiveInfo dartdocInfo, Element elementBeingDocumented,
-      {bool includeSummary = false}) {
-    // TODO(dantup): We're reusing this in parameter information - move it
-    // somewhere shared?
-    Element? element = elementBeingDocumented;
-    if (element is FieldFormalParameterElement) {
-      element = element.field;
-    }
-    if (element is ParameterElement) {
-      element = element.enclosingElement3;
-    }
-    if (element == null) {
-      // This can happen when the code is invalid, such as having a field formal
-      // parameter for a field that does not exist.
-      return null;
-    }
-
-    Element? documentedElement;
-    Element? documentedGetter;
-
-    // Look for documentation comments of overridden members
-    var overridden = findOverriddenElements(element);
-    var candidates = [
-      element,
-      ...overridden.superElements,
-      ...overridden.interfaceElements,
-      if (element case PropertyAccessorElement(variable2: var variable?))
-        variable
-    ];
-    for (var candidate in candidates) {
-      if (candidate.documentationComment != null) {
-        documentedElement = candidate;
-        break;
-      }
-      if (documentedGetter == null &&
-          candidate is PropertyAccessorElement &&
-          candidate.isSetter) {
-        var getter = candidate.correspondingGetter;
-        if (getter != null && getter.documentationComment != null) {
-          documentedGetter = getter;
-        }
-      }
-    }
-
-    // Use documentation of a corresponding getter if setters don't have it
-    documentedElement ??= documentedGetter;
-    if (documentedElement == null) {
-      return null;
-    }
-
-    var rawDoc = documentedElement.documentationComment;
-    if (rawDoc == null) {
-      return null;
-    }
-    var result =
-        dartdocInfo.processDartdoc(rawDoc, includeSummary: includeSummary);
-
-    var documentedElementClass = documentedElement.enclosingElement3;
-    if (documentedElementClass != null &&
-        documentedElementClass != element.enclosingElement3) {
-      var documentedClass = documentedElementClass.displayName;
-      result.full = '${result.full}\n\nCopied from `$documentedClass`.';
-    }
-
-    return result;
-  }
-
-  /// Compute documentation for [element] and return either the summary or full
-  /// docs (or `null`) depending on `preference`.
-  static String? computePreferredDocumentation(
-    DartdocDirectiveInfo dartdocInfo,
-    Element element,
-    DocumentationPreference preference,
-  ) {
-    if (preference == DocumentationPreference.none) {
-      return null;
-    }
-
-    var doc = computeDocumentation(
-      dartdocInfo,
-      element,
-      includeSummary: preference == DocumentationPreference.summary,
-    );
-
-    return doc is DocumentationWithSummary ? doc.summary : doc?.full;
-  }
-
   static DartType? _getTypeOfDeclarationOrReference(Expression node) {
     if (node is SimpleIdentifier) {
       var element = node.staticElement;
@@ -392,11 +304,3 @@ class DartUnitHoverComputer {
     return node.staticType;
   }
 }
-
-/// The type of documentation the user prefers to see in hovers and other
-/// related displays in their editor.
-enum DocumentationPreference {
-  none,
-  summary,
-  full,
-}

pkg/analysis_server/lib/src/computer/computer_signature.dart

@@ -2,7 +2,7 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'package:analysis_server/src/computer/computer_hover.dart';
+import 'package:analysis_server/src/computer/computer_documentation.dart';
 import 'package:analysis_server/src/protocol_server.dart' hide Element;
 import 'package:analysis_server/src/utilities/extensions/ast.dart';
 import 'package:analyzer/dart/ast/ast.dart';
@@ -15,17 +15,18 @@ import 'package:analyzer/src/dartdoc/dartdoc_directive_info.dart';
 /// A computer for the signature at the specified offset of a Dart
 /// [CompilationUnit].
 class DartUnitSignatureComputer {
-  final DartdocDirectiveInfo _dartdocInfo;
   final AstNode? _node;
   late ArgumentList _argumentList;
   final DocumentationPreference documentationPreference;
+  final DartDocumentationComputer _documentationComputer;
 
   DartUnitSignatureComputer(
-    this._dartdocInfo,
+    DartdocDirectiveInfo dartdocInfo,
     CompilationUnit unit,
     int offset, {
     this.documentationPreference = DocumentationPreference.full,
-  }) : _node = NodeLocator(offset).searchWithin(unit);
+  })  : _documentationComputer = DartDocumentationComputer(dartdocInfo),
+        _node = NodeLocator(offset).searchWithin(unit);
 
   /// The [ArgumentList] node located by [compute].
   ArgumentList get argumentList => _argumentList;
@@ -75,8 +76,7 @@ class DartUnitSignatureComputer {
 
     _argumentList = argumentList;
     var convertedParameters = parameters.map((p) => _convertParam(p)).toList();
-    var dartdoc = DartUnitHoverComputer.computePreferredDocumentation(
-      _dartdocInfo,
+    var dartdoc = _documentationComputer.computePreferred(
       element,
       documentationPreference,
     );

pkg/analysis_server/lib/src/computer/computer_type_arguments_signature.dart

@@ -3,7 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:analysis_server/lsp_protocol/protocol.dart' as lsp;
-import 'package:analysis_server/src/computer/computer_hover.dart';
+import 'package:analysis_server/src/computer/computer_documentation.dart';
 import 'package:analysis_server/src/lsp/dartdoc.dart';
 import 'package:analysis_server/src/lsp/mapping.dart';
 import 'package:analyzer/dart/ast/ast.dart';
@@ -16,19 +16,20 @@ import 'package:analyzer/src/dartdoc/dartdoc_directive_info.dart';
 /// the [TypeArgumentList] surrounding the specified offset of a Dart
 /// [CompilationUnit].
 class DartTypeArgumentsSignatureComputer {
-  final DartdocDirectiveInfo _dartdocInfo;
   final AstNode? _node;
   final Set<lsp.MarkupKind>? preferredFormats;
   late TypeArgumentList _argumentList;
   final DocumentationPreference documentationPreference;
+  final DartDocumentationComputer _documentationComputer;
 
   DartTypeArgumentsSignatureComputer(
-    this._dartdocInfo,
+    DartdocDirectiveInfo dartdocInfo,
     CompilationUnit unit,
     int offset,
     this.preferredFormats, {
     this.documentationPreference = DocumentationPreference.full,
-  }) : _node = NodeLocator(offset).searchWithin(unit);
+  })  : _documentationComputer = DartDocumentationComputer(dartdocInfo),
+        _node = NodeLocator(offset).searchWithin(unit);
 
   /// The [TypeArgumentList] node located by [compute].
   TypeArgumentList get argumentList => _argumentList;
@@ -56,8 +57,8 @@ class DartTypeArgumentsSignatureComputer {
     _argumentList = argumentList;
 
     var label = element.getDisplayString();
-    var documentation = DartUnitHoverComputer.computePreferredDocumentation(
-        _dartdocInfo, element, documentationPreference);
+    var documentation = _documentationComputer.computePreferred(
+        element, documentationPreference);
 
     return _toSignatureHelp(
       label,

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

@@ -2,7 +2,7 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
-import 'package:analysis_server/src/computer/computer_hover.dart';
+import 'package:analysis_server/src/computer/computer_documentation.dart';
 import 'package:collection/collection.dart';
 import 'package:path/path.dart' as path;
 

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

@@ -5,7 +5,7 @@
 import 'dart:math' as math;
 
 import 'package:analysis_server/lsp_protocol/protocol.dart' hide Declaration;
-import 'package:analysis_server/src/computer/computer_hover.dart';
+import 'package:analysis_server/src/computer/computer_documentation.dart';
 import 'package:analysis_server/src/lsp/client_capabilities.dart';
 import 'package:analysis_server/src/lsp/constants.dart';
 import 'package:analysis_server/src/lsp/error_or.dart';

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

@@ -3,7 +3,7 @@
 // BSD-style license that can be found in the LICENSE file.
 
 import 'package:analysis_server/lsp_protocol/protocol.dart' hide Element;
-import 'package:analysis_server/src/computer/computer_hover.dart';
+import 'package:analysis_server/src/computer/computer_documentation.dart';
 import 'package:analysis_server/src/lsp/client_capabilities.dart';
 import 'package:analysis_server/src/lsp/constants.dart';
 import 'package:analysis_server/src/lsp/error_or.dart';
@@ -129,9 +129,8 @@ class CompletionResolveHandler
         if (element != null) {
           var formats = clientCapabilities.completionDocumentationFormats;
           var dartDocInfo = server.getDartdocDirectiveInfoForSession(session);
-          var dartDoc = DartUnitHoverComputer.computePreferredDocumentation(
-              dartDocInfo,
-              element,
+          var dartDocComputer = DartDocumentationComputer(dartDocInfo);
+          var dartDoc = dartDocComputer.computePreferred(element,
               server.lspClientConfiguration.global.preferredDocumentation);
           // `dartDoc` can be both null or empty.
           documentation = dartDoc != null && dartDoc.isNotEmpty

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

@@ -6,7 +6,7 @@ import 'package:analysis_server/lsp_protocol/protocol.dart' as lsp;
 import 'package:analysis_server/lsp_protocol/protocol.dart' hide Declaration;
 import 'package:analysis_server/src/analysis_server.dart';
 import 'package:analysis_server/src/collections.dart';
-import 'package:analysis_server/src/computer/computer_hover.dart';
+import 'package:analysis_server/src/computer/computer_documentation.dart';
 import 'package:analysis_server/src/lsp/client_capabilities.dart';
 import 'package:analysis_server/src/lsp/constants.dart' as lsp;
 import 'package:analysis_server/src/lsp/constants.dart';