[Java. Logging] Add javadocs for the most important loggers

IDEA-331693

GitOrigin-RevId: 25cace5a0e0919394ac78ca066b1a1936282fc5b

java/java-impl/src/com/intellij/logging/JvmLogger.kt

@@ -9,29 +9,85 @@ import com.intellij.openapi.project.Project
 import com.intellij.psi.PsiClass
 import com.intellij.psi.PsiElement
 
+/**
+ * Extension point representing a JVM logger. Extensions of this EP are used to store information about concrete logger and provide
+ * the way to generate a logger at the class.
+ */
 interface JvmLogger {
+  /**
+   * This field represents fully qualified name of the logger's type
+   */
   val loggerTypeName: String
 
+  /**
+   * This field is used to determine the order of loggers in the settings
+   * @see com.intellij.settings.JvmLoggingConfigurable
+   */
   val priority: Int
 
+  /**
+   * Determines if the logger should only be used when user didn't specify the preferred logger in the settings.
+   * For example, it happens after creation of the new project.
+   *
+   * @return true if the logger should only be used during startup, false otherwise
+   * @see com.intellij.logging.UnspecifiedLogger
+   */
   fun isOnlyOnStartup() = false
 
+  /**
+   * Inserts a logger element at the specified class.
+   *
+   * @param project the project context
+   * @param clazz the class where the logger element will be inserted
+   * @return the inserted logger element, or null if the operation fails
+   */
   fun insertLoggerAtClass(project: Project, clazz: PsiClass): PsiElement? {
-    val logger = createLoggerElementText(project, clazz) ?: return null
+    val logger = createLogger(project, clazz) ?: return null
     return WriteAction.compute<PsiElement?, Exception> {
       insertLoggerAtClass(project, clazz, logger)
     }
   }
 
+  /**
+   * Inner method for inserting the logger at the specified class. Should only be invoked inside WriteAction.
+   * @param project the project context
+   * @param clazz the class where the logger element will be inserted
+   * @param logger PsiElement, corresponding to the logger to be inserted
+   */
   fun insertLoggerAtClass(project: Project, clazz: PsiClass, logger: PsiElement): PsiElement?
 
+  /**
+   * Determines if the logger is available for the given project.
+   *
+   * @param project the project context
+   * @return true if the logger is available, false otherwise
+   */
   fun isAvailable(project: Project?) : Boolean
 
+  /**
+   * Determines if the logger is available for the given module.
+   *
+   * @param module the module context
+   * @return true if the logger is available, false otherwise
+   */
   fun isAvailable(module: Module?) : Boolean
 
+  /**
+   * Determines if it is possible to place a logger at the specified class.
+   *
+   * @param clazz the class where the logger will be placed
+   * @return true if it is possible to place a logger, false otherwise
+   */
   fun isPossibleToPlaceLoggerAtClass(clazz: PsiClass) : Boolean
 
-  fun createLoggerElementText(project: Project, clazz: PsiClass): PsiElement?
+  /**
+   * Creates a logger element for inserting into a class.
+   *
+   * @param project the project context
+   * @param clazz the class where the logger element will be inserted
+   * @return the created logger element, or null if creation fails
+   */
+  fun createLogger(project: Project, clazz: PsiClass): PsiElement?
 
   companion object {
     private val EP_NAME = ExtensionPointName<JvmLogger>("com.intellij.jvm.logging")

java/java-impl/src/com/intellij/logging/JvmLoggerFieldDelegate.kt

@@ -8,6 +8,15 @@ import com.intellij.psi.*
 import com.intellij.psi.codeStyle.JavaCodeStyleManager
 import com.intellij.psi.util.PsiUtil
 
+/**
+ * Represents a delegate implementation of the JvmLogger interface that is used to insert loggers which are [PsiField].
+ *
+ * @property factoryName The name of the factory class used to create the logger.
+ * @property methodName The name of the method in the factory class used to get the logger.
+ * @property classNamePattern The pattern used to format the class name when creating the logger element.
+ * @property loggerTypeName The fully qualified name of the logger's type.
+ * @property priority The priority of the logger, used for ordering in the settings.
+ */
 class JvmLoggerFieldDelegate(
   private val factoryName: String,
   private val methodName: String,
@@ -27,7 +36,7 @@ class JvmLoggerFieldDelegate(
   override fun isPossibleToPlaceLoggerAtClass(clazz: PsiClass): Boolean = clazz
     .fields.any { it.name == LOGGER_IDENTIFIER || it.type.canonicalText == loggerTypeName }.not()
 
-  override fun createLoggerElementText(project: Project, clazz: PsiClass): PsiField? {
+  override fun createLogger(project: Project, clazz: PsiClass): PsiField? {
     val factory = JavaPsiFacade.getElementFactory(project)
     val className = clazz.name ?: return null
     val fieldText = "$loggerTypeName $LOGGER_IDENTIFIER = ${factoryName}.$methodName(${

java/java-impl/src/com/intellij/logging/UnspecifiedLogger.kt

@@ -6,6 +6,10 @@ import com.intellij.openapi.project.Project
 import com.intellij.psi.PsiClass
 import com.intellij.psi.PsiElement
 
+/**
+ * This class represents logger which user has after creation of the project. This is fake logger which is only necessary to support
+ * "unspecified" state, e.g. where there is no preferred logger selected.
+ */
 class UnspecifiedLogger : JvmLogger {
   override val loggerTypeName: String = "Unspecified"
   override val priority: Int = 1000
@@ -21,7 +25,7 @@ class UnspecifiedLogger : JvmLogger {
 
   override fun isPossibleToPlaceLoggerAtClass(clazz: PsiClass): Boolean = false
 
-  override fun createLoggerElementText(project: Project, clazz: PsiClass): PsiElement = throw UnsupportedOperationException()
+  override fun createLogger(project: Project, clazz: PsiClass): PsiElement = throw UnsupportedOperationException()
 
   override fun toString(): String = UNSPECIFIED_LOGGER_NAME
 

plugins/lombok/src/main/java/de/plushnikov/intellij/plugin/logging/JvmLoggerAnnotationDelegate.kt

@@ -11,6 +11,13 @@ import com.intellij.psi.PsiElement
 import com.intellij.psi.codeStyle.JavaCodeStyleManager
 import de.plushnikov.intellij.plugin.util.LombokLibraryUtil
 
+/**
+ * Represents a delegate implementation of the JvmLogger interface that is used to insert loggers which are [PsiAnnotation].
+ * Use it to handle with Lombok loggers
+ * @param fieldLoggerName the fully qualified name of the logger's type.
+ * @param loggerTypeName the fully qualified name of annotation used to generate logger
+ * @param priority the priority of the logger.
+ */
 class JvmLoggerAnnotationDelegate(
   private val fieldLoggerName: String,
   override val loggerTypeName: String,
@@ -32,7 +39,7 @@ class JvmLoggerAnnotationDelegate(
 
   override fun isPossibleToPlaceLoggerAtClass(clazz: PsiClass): Boolean = clazz.hasAnnotation(loggerTypeName).not()
 
-  override fun createLoggerElementText(project: Project, clazz: PsiClass): PsiAnnotation {
+  override fun createLogger(project: Project, clazz: PsiClass): PsiAnnotation {
     val factory = JavaPsiFacade.getElementFactory(project)
     return factory.createAnnotationFromText("@$loggerTypeName", clazz)
   }