[javadoc] Add javadoc for JavaDocFragmentAnchorCache

#IDEA-376337

GitOrigin-RevId: 67922e2919719215cbeff4ab8c490c195c31d8f0

java/java-analysis-impl/src/com/intellij/codeInsight/daemon/impl/analysis/JavaNamesHighlightVisitor.java

@@ -103,7 +103,7 @@ final class JavaNamesHighlightVisitor extends JavaElementVisitor implements High
     }
     else if (value instanceof PsiDocFragmentName docFragmentName) {
       final Pair<PsiClass, JavaDocFragmentData> fragmentData = computeIfSmartMode(value.getProject(), () -> {
-        return JavaDocFragmentAnchorCacheKt.getAnchor(value.getProject(), docFragmentName);
+        return JavaDocFragmentAnchorCacheKt.resolveJavaDocFragment(value.getProject(), docFragmentName);
       });
       if (fragmentData != null) {
         myHolder.add(HighlightNamesUtil.highlightFragmentReference(docFragmentName));

java/java-impl/src/com/intellij/codeInsight/completion/JavaDocCompletionContributor.java

@@ -141,7 +141,7 @@ public final class JavaDocCompletionContributor extends CompletionContributor im
           final PsiClass classRef = parent instanceof PsiDocFragmentRef ? ((PsiDocFragmentRef)docFragmentName.getParent()).getScope() : null;
           final String fqn = classRef == null ? null : classRef.getQualifiedName();
           if (fqn != null) {
-            for (JavaDocFragmentData anchor : JavaDocFragmentAnchorCacheKt.getAnchors(position.getProject(), fqn)) {
+            for (JavaDocFragmentData anchor : JavaDocFragmentAnchorCacheKt.getJavaDocFragmentsForClass(position.getProject(), fqn)) {
               result.addElement(LookupElementBuilder.create(anchor.getName()).withIcon(AllIcons.Nodes.Related));
             }
           }

java/java-impl/src/com/intellij/psi/impl/JavaPsiImplementationHelperImpl.java

@@ -454,7 +454,7 @@ public class JavaPsiImplementationHelperImpl extends JavaPsiImplementationHelper
   public @Nullable PsiSymbolReference getFragmentNameSymbol(@NotNull PsiDocFragmentName fragmentName) {
     if (DumbService.getInstance(myProject).isDumb()) return null;
 
-    final Pair<PsiClass, JavaDocFragmentData> fragmentData = JavaDocFragmentAnchorCacheKt.getAnchor(myProject, fragmentName);
+    final Pair<PsiClass, JavaDocFragmentData> fragmentData = JavaDocFragmentAnchorCacheKt.resolveJavaDocFragment(myProject, fragmentName);
     if (fragmentData == null) return null;
     final int offset = fragmentData.getSecond().getOffset();
 

java/java-indexing-impl/src/com/intellij/codeInsight/javadoc/index/JavaDocFragmentAnchorCache.kt

@@ -17,6 +17,12 @@ import java.util.regex.Pattern
 @JvmField
 val NAME: ID<String, LinkedHashSet<JavaDocFragmentData>> = ID.create("java.javadoc.fragment.anchors")
 
+/**
+ * Data associated with a JavaDoc fragment (e.g. `<p id=my-fragment-id></p>`).
+ *
+ * @param name fragment name
+ * @param offset fragment offset in the containing file
+ */
 data class JavaDocFragmentData(val name: String, val offset: Int)
 
 @Service(Service.Level.PROJECT)
@@ -65,17 +71,24 @@ private class JavaDocFragmentCacheService {
   }
 }
 
-fun getAnchors(project: Project, fqnOrPackage: String): LinkedHashSet<JavaDocFragmentData> {
-  return project.service<JavaDocFragmentCacheService>().getAnchors(project, fqnOrPackage)
+/**
+ * Resolves all fragment data for the class corresponding to the given fully qualified name.
+ */
+fun getJavaDocFragmentsForClass(project: Project, fqn: String): LinkedHashSet<JavaDocFragmentData> {
+  return project.service<JavaDocFragmentCacheService>().getAnchors(project, fqn)
 }
 
-fun getAnchor(project: Project, fragmentName: PsiDocFragmentName): Pair<PsiClass, JavaDocFragmentData>? {
+/**
+ * For a given `PsiDocFragmentName`, e.g. (`my-id` in `{@link MyClass##my-id …}`),
+ * returns the fragment data and its containing class if found.
+ */
+fun resolveJavaDocFragment(project: Project, fragmentName: PsiDocFragmentName): Pair<PsiClass, JavaDocFragmentData>? {
   if (DumbService.getInstance(project).isDumb) return null
 
   val psiClass = fragmentName.getScope()
   val fqn = psiClass?.qualifiedName ?: return null
 
-  val data = getAnchors(project, fqn).firstOrNull { data: JavaDocFragmentData -> data.name == fragmentName.text }
+  val data = getJavaDocFragmentsForClass(project, fqn).firstOrNull { data: JavaDocFragmentData? -> data!!.name == fragmentName.text }
              ?: return null
 
   return psiClass to data

java/java-tests/testSrc/com/intellij/java/indexing/JavaDocFragmentAnchorCacheTest.java

@@ -37,7 +37,7 @@ public class JavaDocFragmentAnchorCacheTest extends LightJavaCodeInsightTestCase
 
     Project project = getProject();
 
-    Collection<JavaDocFragmentData> anchors = JavaDocFragmentAnchorCacheKt.getAnchors(project, "p.A");
+    Collection<JavaDocFragmentData> anchors = JavaDocFragmentAnchorCacheKt.getJavaDocFragmentsForClass(project, "p.A");
     assertNotNull(anchors);
     assertContainsElements(anchors,
                            new JavaDocFragmentData("equivalenceRelation", 25),