Add some minor docs

Kotlin · Jul 28, 2023 · 5fdf4da · 5fdf4da
1 parent c4d2357
commit 5fdf4da
Show file tree

Hide file tree

Showing 6 changed files with 54 additions and 33 deletions.
diff --git a/build-logic/src/main/kotlin/org/jetbrains/conventions/kotlin-jvm.gradle.kts b/build-logic/src/main/kotlin/org/jetbrains/conventions/kotlin-jvm.gradle.kts
@@ -25,7 +25,6 @@ tasks.withType<KotlinCompile>().configureEach {
                 "-Xskip-metadata-version-check",
                 // need 1.4 support, otherwise there might be problems with Gradle 6.x (it's bundling Kotlin 1.4)
                 "-Xsuppress-version-warnings",
-               // "-XXLanguage:+SamConversionForKotlinFunctions",
             )
         )
         allWarningsAsErrors.set(true)

diff --git a/...lugin/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/kdoc/ResolveKDocLink.kt b/...lugin/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/kdoc/ResolveKDocLink.kt
@@ -8,7 +8,7 @@ import org.jetbrains.kotlin.name.Name
 import org.jetbrains.kotlin.psi.KtElement
 
 /**
- *  Give priority to callable independent of scope order
+ *  Callable have priority independent of scope order
  */
 private fun KtAnalysisSession.searchInScope(scope: KtScope, inndexOfLinkSegment: Int, linkSegments: List<Name>): KtSymbol? {
     val identifier = linkSegments[inndexOfLinkSegment]
@@ -37,6 +37,6 @@ internal fun KtAnalysisSession.resolveKDocLink(link: String, contextElement: KtE
     val  file = contextElement.containingKtFile
     val scope =  file.getScopeContextForPosition(contextElement).getCompositeScope()
 
-    return searchInScope(scope, 0, linkParts)
-        ?: searchInScope(ROOT_PACKAGE_SYMBOL.getPackageScope(), 0, linkParts)
+    return searchInScope(scope, 0, linkParts) // relative link
+        ?: searchInScope(ROOT_PACKAGE_SYMBOL.getPackageScope(), 0, linkParts) // fq link
 }
diff --git a/...in/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/AnnotationTranslator.kt b/...in/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/AnnotationTranslator.kt
@@ -15,6 +15,9 @@ import org.jetbrains.kotlin.name.FqName
 import org.jetbrains.kotlin.name.Name
 import org.jetbrains.kotlin.psi.KtFile
 
+/**
+ * Map [KtAnnotationApplication] to Dokka [Annotations.Annotation]
+ */
 internal class AnnotationTranslator {
     private fun KtAnalysisSession.getFileLevelAnnotationsFrom(symbol: KtSymbol) =
         if (symbol.origin != KtSymbolOrigin.SOURCE)
@@ -26,6 +29,9 @@ internal class AnnotationTranslator {
     private fun KtAnalysisSession.getDirectAnnotationsFrom(annotated: KtAnnotated) =
         annotated.annotations.map { toDokkaAnnotation(it) }
 
+    /**
+     * @return direct annotations and file-level annotations
+     */
     fun KtAnalysisSession.getAllAnnotationsFrom(annotated: KtAnnotated): List<Annotations.Annotation> {
         val directAnnotations = getDirectAnnotationsFrom(annotated)
         val fileLevelAnnotations = (annotated as? KtSymbol)?.let { getFileLevelAnnotationsFrom(it) } ?: emptyList()
@@ -116,6 +122,10 @@ internal class AnnotationTranslator {
     companion object {
         val mustBeDocumentedAnnotation = ClassId(FqName("kotlin.annotation"), FqName("MustBeDocumented"), false)
         private val parameterNameAnnotation = ClassId(FqName("kotlin"), FqName("ParameterName"), false)
+
+        /**
+         * Functional types can have **generated** [ParameterName] annotation
+         */
         internal fun KtAnnotated.getPresentableName(): String? =
             this.annotationsByClassId(parameterNameAnnotation)
                 .firstOrNull()?.arguments?.firstOrNull { it.name == Name.identifier("name") }?.expression?.let { it as? KtConstantAnnotationValue }

diff --git a/...brains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt b/...brains/dokka/analysis/kotlin/symbols/translators/DefaultSymbolToDocumentableTranslator.kt
@@ -28,7 +28,6 @@ import org.jetbrains.kotlin.KtNodeTypes
 import org.jetbrains.kotlin.analysis.api.*
 import org.jetbrains.kotlin.analysis.api.annotations.KtAnnotated
 import org.jetbrains.kotlin.analysis.api.symbols.*
-import org.jetbrains.kotlin.analysis.api.symbols.markers.KtNamedSymbol
 import org.jetbrains.kotlin.analysis.api.symbols.markers.KtSymbolWithModality
 import org.jetbrains.kotlin.analysis.api.symbols.markers.KtSymbolWithVisibility
 import org.jetbrains.kotlin.analysis.api.types.*
@@ -67,37 +66,16 @@ class DefaultSymbolToDocumentableTranslator(context: DokkaContext) : AsyncSource
     }
 }
 
-class TranslatorError(message: String, cause: Throwable?) : IllegalStateException(message, cause)
-
-inline fun <R> KtAnalysisSession.withExceptionCatcher(symbol: KtSymbol, action: KtAnalysisSession.() -> R): R =
-    try {
-        action()
-    } catch (e: TranslatorError) {
-        throw e
-    } catch (e: Throwable) {
-        val file = try {
-            symbol.psi?.containingFile?.virtualFile?.path
-        } catch (e: Throwable) {
-            "[$e]"
-        }
-        val textRange = try {
-            symbol.psi?.textRange.toString()
-        } catch (e: Throwable) {
-            "[$e]"
-        }
-        throw TranslatorError(
-            "Error in translating of symbol (${(symbol as? KtNamedSymbol)?.name}) $symbol in file: $file, $textRange",
-            e
-        )
-    }
-
 internal fun <T : Bound> T.wrapWithVariance(variance: org.jetbrains.kotlin.types.Variance) =
     when (variance) {
         org.jetbrains.kotlin.types.Variance.INVARIANT -> Invariance(this)
         org.jetbrains.kotlin.types.Variance.IN_VARIANCE -> Contravariance(this)
         org.jetbrains.kotlin.types.Variance.OUT_VARIANCE -> Covariance(this)
     }
 
+/**
+ * Maps [KtSymbol] to Documentable model [Documentable]
+ */
 internal class DokkaSymbolVisitor(
     private val sourceSet: DokkaConfiguration.DokkaSourceSet,
     private val moduleName: String,
@@ -109,7 +87,7 @@ internal class DokkaSymbolVisitor(
     private var typeTranslator = TypeTranslator(sourceSet, annotationTranslator)
 
     /**
-     * to avoid recursive classes
+     * To avoid recursive classes
      * e.g.
      * open class Klass() {
      *   object Default : Klass()
@@ -134,7 +112,7 @@ internal class DokkaSymbolVisitor(
         } == true
     }
 
-    internal fun visitModule(): DModule {
+    fun visitModule(): DModule {
         val ktFiles: List<KtFile> = getPsiFilesFromPaths(
             analysisContext.project,
             getSourceFilePaths(sourceSet.sourceRoots.map { it.canonicalPath })

diff --git a/...rc/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/TranslatorError.kt b/...rc/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/TranslatorError.kt
@@ -0,0 +1,29 @@
+package org.jetbrains.dokka.analysis.kotlin.symbols.translators
+
+import org.jetbrains.kotlin.analysis.api.KtAnalysisSession
+import org.jetbrains.kotlin.analysis.api.symbols.KtSymbol
+import org.jetbrains.kotlin.analysis.api.symbols.markers.KtNamedSymbol
+
+class TranslatorError(message: String, cause: Throwable?) : IllegalStateException(message, cause)
+
+inline fun <R> KtAnalysisSession.withExceptionCatcher(symbol: KtSymbol, action: KtAnalysisSession.() -> R): R =
+    try {
+        action()
+    } catch (e: TranslatorError) {
+        throw e
+    } catch (e: Throwable) {
+        val file = try {
+            symbol.psi?.containingFile?.virtualFile?.path
+        } catch (e: Throwable) {
+            "[$e]"
+        }
+        val textRange = try {
+            symbol.psi?.textRange.toString()
+        } catch (e: Throwable) {
+            "[$e]"
+        }
+        throw TranslatorError(
+            "Error in translating of symbol (${(symbol as? KtNamedSymbol)?.name}) $symbol in file: $file, $textRange",
+            e
+        )
+    }
diff --git a/...src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/TypeTranslator.kt b/...src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/translators/TypeTranslator.kt
@@ -13,8 +13,13 @@ import org.jetbrains.kotlin.analysis.api.annotations.*
 import org.jetbrains.kotlin.analysis.api.symbols.*
 import org.jetbrains.kotlin.analysis.api.types.*
 
-const val ERROR_CLASS_NAME = "<ERROR CLASS>"
+internal const val ERROR_CLASS_NAME = "<ERROR CLASS>"
 
+/**
+ * Maps [KtType] to Dokka [Bound] or [TypeConstructorWithKind].
+ *
+ * Also, build [AncestryNode] tree from [KtType]
+ */
 internal class TypeTranslator(
     private val sourceSet: DokkaConfiguration.DokkaSourceSet,
     private val annotationTranslator: AnnotationTranslator
@@ -65,7 +70,7 @@ internal class TypeTranslator(
             )
         )
 
-    internal fun KtAnalysisSession.toBoundFrom(type: KtType): Bound =
+    fun KtAnalysisSession.toBoundFrom(type: KtType): Bound =
         when (type) {
             is KtUsualClassType -> {
                 if (type.classSymbol is KtTypeAliasSymbol) toTypeConstructorFromTypeAliased(type)