[Java. Logging] Add javadoc for some methods LoggingArgumentSymbolReferenceProvider.kt and rename DefUsage to PsiElementUsage

IDEA-342484

GitOrigin-RevId: e40968673369c6b796f4a71dce087561bc7aad95

java/java-impl/src/com/siyeh/ig/format/PsiElementUsage.java

@@ -8,10 +8,14 @@ import com.intellij.psi.PsiElement;
 import com.intellij.psi.PsiFile;
 import org.jetbrains.annotations.NotNull;
 
-public class DefUsage implements PsiUsage {
+/**
+ * A class, which represents a PsiUsage, based on concrete PsiElement.
+ * @see PsiUsage
+ */
+public class PsiElementUsage implements PsiUsage {
   private final @NotNull PsiElement myArg;
 
-  public DefUsage(@NotNull PsiElement arg) {
+  public PsiElementUsage(@NotNull PsiElement arg) {
     myArg = arg;
   }
 

java/java-impl/src/com/siyeh/ig/format/StringFormatUsageSearcher.java

@@ -36,7 +36,7 @@ public final class StringFormatUsageSearcher implements UsageSearcher {
       .flatMap(function)
       .filter(ref -> ref.resolvesTo(symbol))
       .<Usage>map(PsiUsage::textUsage)
-      .append(List.of(new DefUsage(arg)))
+      .append(List.of(new PsiElementUsage(arg)))
       .toList();
   }
 }

jvm/jvm-analysis-impl/src/com/intellij/analysis/logging/highlighting/LoggingPlaceholderAnnotator.kt

@@ -2,7 +2,7 @@
 package com.intellij.analysis.logging.highlighting
 
 import com.intellij.analysis.customization.console.ClassFinderConsoleColorsPage
-import com.intellij.analysis.logging.resolve.getAlignedPlaceholderCount
+import com.intellij.analysis.logging.resolve.getAdjustedPlaceholderList
 import com.intellij.analysis.logging.resolve.getContext
 import com.intellij.analysis.logging.resolve.getPlaceholderRanges
 import com.intellij.lang.annotation.AnnotationHolder
@@ -43,6 +43,6 @@ class LoggingPlaceholderAnnotator : Annotator {
       ranges.filterNotNull()
     }
 
-    return getAlignedPlaceholderCount(textRangeList, context)
+    return getAdjustedPlaceholderList(textRangeList, context)
   }
 }

jvm/jvm-analysis-impl/src/com/intellij/analysis/logging/resolve/LoggingArgumentSymbolReferenceProvider.kt

@@ -36,9 +36,15 @@ fun getLogArgumentReferences(uExpression: UExpression): List<PsiSymbolReference>
     }
   }.flatten()
 
-  return getAlignedPlaceholderCount(loggerReferenceList, context)
+  return getAdjustedPlaceholderList(loggerReferenceList, context)
 }
 
+/**
+ * Retrieves the context of a placeholder in a logger statement.
+ *
+ * @param uExpression The UExpression representing the placeholder.
+ * @return The PlaceholderContext object if the placeholder context is found, otherwise null.
+ */
 internal fun getContext(uExpression: UExpression): PlaceholderContext? {
   val uCallExpression = uExpression.getParentOfType<UCallExpression>() ?: return null
   val logMethod = detectLoggerMethod(uCallExpression) ?: return null
@@ -48,7 +54,15 @@ internal fun getContext(uExpression: UExpression): PlaceholderContext? {
   return context
 }
 
-internal fun <T> getAlignedPlaceholderCount(placeholderList: List<T>, context: PlaceholderContext): List<T>? {
+/**
+ * Retrieves a list of placeholders, for which there is a resolve argument exists.
+ * This list might be different from initial input, because, for example, the number of arguments is less,
+ * than the number of placeholders or last argument could be an exception.
+ * @param placeholderList The list of placeholders. It might be a text ranges or
+ * @param context The placeholder context.
+ * @return The adjusted list of placeholders, or null if the logger type is not supported.
+ */
+internal fun <T> getAdjustedPlaceholderList(placeholderList: List<T>, context: PlaceholderContext): List<T>? {
   val placeholderParametersSize = context.placeholderParameters.size
   return when (context.loggerType) {
     SLF4J -> {
@@ -69,6 +83,14 @@ internal fun <T> getAlignedPlaceholderCount(placeholderList: List<T>, context: P
   }
 }
 
+/**
+ * Retrieves a list of placeholder ranges from the given `context`.
+ *
+ * @param context The [PlaceholderContext] object containing the necessary data for retrieving placeholder ranges.
+ * @return A list of PlaceholderRanges or null if the logStringArgument is null or the number of placeholders is not exact.
+ * @see PlaceholderContext
+ * @see PlaceholderRanges
+ */
 internal fun getPlaceholderRanges(context: PlaceholderContext): List<PlaceholderRanges>? {
   val logStringText = context.logStringArgument.sourcePsi?.text ?: return null
   val type = if (isKotlinMultilineString(context.logStringArgument, logStringText)) {

jvm/jvm-analysis-impl/src/com/intellij/analysis/logging/resolve/LoggingArgumentUsageSearcher.kt

@@ -7,7 +7,7 @@ import com.intellij.find.usages.api.UsageSearchParameters
 import com.intellij.find.usages.api.UsageSearcher
 import com.intellij.model.psi.PsiSymbolReference
 import com.intellij.util.Query
-import com.siyeh.ig.format.DefUsage
+import com.siyeh.ig.format.PsiElementUsage
 
 class LoggingArgumentUsageSearcher : UsageSearcher {
   override fun collectSearchRequests(parameters: UsageSearchParameters): Collection<Query<out Usage>> {
@@ -16,7 +16,7 @@ class LoggingArgumentUsageSearcher : UsageSearcher {
     val uLiteralExpression = target.getPlaceholderString() ?: return emptyList()
     return getLogArgumentReferences(uLiteralExpression)?.let {
       it.filter { ref: PsiSymbolReference -> ref.resolvesTo(target) }
-        .flatMap { usage -> listOf(PsiUsage.textUsage(usage), DefUsage(target.expression)) }
+        .flatMap { usage -> listOf(PsiUsage.textUsage(usage), PsiElementUsage(target.expression)) }
         .map { psiUsage -> LoggingArgumentPsiUsageQuery(psiUsage) }
     } ?: emptyList()
   }