Enhancement: Add KDoc comments for validation result classes and improve parameter naming

Author: xterao

src/main/kotlin/org/domaframework/doma/intellij/common/sql/foritem/ForDeclarationDaoBaseItem.kt

@@ -40,8 +40,7 @@ class ForDeclarationDaoBaseItem(
             SqlElFieldAccessorChildElementValidator(
                 blocks,
                 element.containingFile,
-                "",
-                daoParameter,
+                topDaoParameter = daoParameter,
             )
 
         var lastType: PsiParentClass? = null

src/main/kotlin/org/domaframework/doma/intellij/common/sql/validator/result/ValidationCompleteResult.kt

@@ -21,6 +21,9 @@ import com.intellij.openapi.util.TextRange
 import com.intellij.psi.PsiElement
 import org.domaframework.doma.intellij.common.psi.PsiParentClass
 
+/**
+ * This class represents successful completion of field access analysis.
+ */
 class ValidationCompleteResult(
     override val identify: PsiElement,
     override val parentClass: PsiParentClass,

src/main/kotlin/org/domaframework/doma/intellij/common/sql/validator/result/ValidationDaoParamResult.kt

@@ -22,6 +22,9 @@ import com.intellij.psi.PsiElement
 import org.domaframework.doma.intellij.bundle.MessageBundle
 import org.domaframework.doma.intellij.common.psi.PsiParentClass
 
+/**
+ * no Dao parameter matching the name of the field access top was found
+ */
 class ValidationDaoParamResult(
     override val identify: PsiElement,
     private val daoName: String,

src/main/kotlin/org/domaframework/doma/intellij/common/sql/validator/result/ValidationPropertyResult.kt

@@ -23,6 +23,9 @@ import com.intellij.psi.PsiElement
 import org.domaframework.doma.intellij.bundle.MessageBundle
 import org.domaframework.doma.intellij.common.psi.PsiParentClass
 
+/**
+ * This class indicates that there is no field or method defined in the class that matches the target name.
+ */
 class ValidationPropertyResult(
     override val identify: PsiElement,
     override val parentClass: PsiParentClass?,

src/main/kotlin/org/domaframework/doma/intellij/common/sql/validator/result/ValidationResult.kt

@@ -57,6 +57,9 @@ abstract class ValidationResult(
         project: Project,
     )
 
+    /**
+     * Highlight level is determined according to the settings
+     */
     protected fun problemHighlightType(
         project: Project,
         shortName: String,

src/main/kotlin/org/domaframework/doma/intellij/inspection/ForDirectiveInspection.kt

@@ -67,6 +67,10 @@ class ForDirectiveInspection(
         forItem?.let { return ForItem(it.item) } ?: return null
     }
 
+    /**
+     * Analyze the field access of the for item definition and finally get the declared type
+     * @return [ValidationResult] is used to display the analysis results.
+     */
     fun checkForItem(blockElements: List<PsiElement>): ValidationResult? {
         val targetElement: PsiElement = blockElements.firstOrNull() ?: return null
         val file = targetElement.containingFile ?: return null