Add documentation and improve java-analysis structure

Kotlin · Jul 4, 2023 · 97b1715 · 97b1715
1 parent 30f2adb
commit 97b1715
Show file tree

Hide file tree

Showing 49 changed files with 200 additions and 178 deletions.
diff --git a/core/api/core.api b/core/api/core.api
@@ -1459,7 +1459,7 @@ public final class org/jetbrains/dokka/model/DocumentableKt {
 }
 
 public abstract interface class org/jetbrains/dokka/model/DocumentableSource {
-	public abstract fun getLineNumber ()Ljava/lang/Integer;
+	public abstract fun computeLineNumber ()Ljava/lang/Integer;
 	public abstract fun getPath ()Ljava/lang/String;
 }
 

diff --git a/core/src/main/kotlin/model/Documentable.kt b/core/src/main/kotlin/model/Documentable.kt
@@ -518,7 +518,15 @@ fun <T> SourceSetDependent<T>?.orEmpty(): SourceSetDependent<T> = this ?: emptyM
 
 interface DocumentableSource {
     val path: String
-    val lineNumber: Int?
+
+    /**
+     * Computes the first line number of the documentable's declaration/signature/identifier.
+     *
+     * Numbering is always 1-based.
+     *
+     * May return null if the sources could not be found - for example, for synthetic/generated declarations.
+     */
+    fun computeLineNumber(): Int?
 }
 
 data class TypeConstructorWithKind(val typeConstructor: TypeConstructor, val kind: ClassKind)
diff --git a/plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt b/plugins/base/src/main/kotlin/transformers/pages/annotations/SinceKotlinTransformer.kt
@@ -3,7 +3,7 @@ package org.jetbrains.dokka.base.transformers.pages.annotations
 
 import org.jetbrains.dokka.DokkaConfiguration
 import org.jetbrains.dokka.Platform
-import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_FILE_NAME
+import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.base.signatures.KotlinSignatureUtils.annotations
 import org.jetbrains.dokka.model.*
 import org.jetbrains.dokka.model.doc.CustomDocTag
@@ -156,7 +156,7 @@ class SinceKotlinTransformer(val context: DokkaContext) : DocumentableTransforme
                             version.toString()
                         )
                     ),
-                    name = MARKDOWN_FILE_NAME
+                    name = MARKDOWN_ELEMENT_FILE_NAME
                 ),
                 "Since Kotlin"
             )

diff --git a/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt b/plugins/base/src/main/kotlin/transformers/pages/comments/DocTagToContentConverter.kt
@@ -2,7 +2,7 @@ package org.jetbrains.dokka.base.transformers.pages.comments
 
 
 import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet
-import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_FILE_NAME
+import org.jetbrains.dokka.analysis.markdown.jb.MARKDOWN_ELEMENT_FILE_NAME
 import org.jetbrains.dokka.model.doc.*
 import org.jetbrains.dokka.model.properties.PropertyContainer
 import org.jetbrains.dokka.model.properties.plus
@@ -262,5 +262,5 @@ open class DocTagToContentConverter : CommentsToContentConverter {
         }
     }
 
-    private fun CustomDocTag.isNonemptyFile() = name == MARKDOWN_FILE_NAME && children.size > 1
+    private fun CustomDocTag.isNonemptyFile() = name == MARKDOWN_ELEMENT_FILE_NAME && children.size > 1
 }
diff --git a/plugins/base/src/main/kotlin/transformers/pages/sourcelinks/SourceLinksTransformer.kt b/plugins/base/src/main/kotlin/transformers/pages/sourcelinks/SourceLinksTransformer.kt
@@ -73,7 +73,7 @@ class SourceLinksTransformer(val context: DokkaContext) : PageTransformer {
         val sourcePath = File(this.path).invariantSeparatorsPath
         val sourceLinkPath = File(sourceLink.path).invariantSeparatorsPath
 
-        val lineNumber = this.lineNumber
+        val lineNumber = this.computeLineNumber()
         return sourceLink.url +
                 sourcePath.split(sourceLinkPath)[1] +
                 sourceLink.lineSuffix +