Skip to content

Commit c821d5b

Browse files
AbdullinAMAbdullinAM
authored
Support context parameters in @param tag (#4398)
* Support context parameters in `@param` tag * Add optional `address` to `Param` tag * Separate type parameters section * Update api
1 parent c773e08 commit c821d5b

File tree

10 files changed

+389
-11
lines changed

10 files changed

+389
-11
lines changed

‎dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/impl/moduledocs/ModuleAndPackageDocumentationReader.kt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,7 @@ import org.jetbrains.dokka.model.DPackage
1414
import org.jetbrains.dokka.model.SourceSetDependent
1515
import org.jetbrains.dokka.model.doc.*
1616
import org.jetbrains.dokka.model.doc.Deprecated
17+
import org.jetbrains.dokka.model.doc.Suppress
1718
import org.jetbrains.dokka.plugability.DokkaContext
1819
import org.jetbrains.dokka.plugability.plugin
1920
import org.jetbrains.dokka.plugability.querySingle
@@ -110,7 +111,7 @@ private class ContextModuleAndPackageDocumentationReader(
110111
is Receiver -> acc.copy(newRoot)
111112
is Constructor -> acc.copy(newRoot)
112113
is Deprecated -> acc.copy(newRoot)
113-
is org.jetbrains.dokka.model.doc.Suppress -> acc.copy(newRoot)
114+
is Suppress -> acc.copy(newRoot)
114115
}
115116
}
116117
}

‎dokka-subprojects/analysis-kotlin-descriptors-compiler/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/descriptors/compiler/translator/KdocMarkdownParser.kt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,8 @@ internal fun parseFromKDocTag(
5656
}
5757
KDocKnownTag.PARAM -> Param(
5858
parseStringToDocNode(it.getContent()),
59-
it.getSubjectName().orEmpty()
59+
it.getSubjectName().orEmpty(),
60+
pointedLink(it),
6061
)
6162
KDocKnownTag.RECEIVER -> Receiver(parseStringToDocNode(it.getContent()))
6263
KDocKnownTag.RETURN -> Return(parseStringToDocNode(it.getContent()))

‎dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/kdoc/KdocMarkdownParser.kt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -63,7 +63,8 @@ internal fun parseFromKDocTag(
6363
}
6464
KDocKnownTag.PARAM -> Param(
6565
parseStringToDocNode(tag.getContent(), externalDRIProvider),
66-
tag.getSubjectName().orEmpty()
66+
tag.getSubjectName().orEmpty(),
67+
pointedLink(tag),
6768
)
6869
KDocKnownTag.RECEIVER -> Receiver(parseStringToDocNode(tag.getContent(), externalDRIProvider))
6970
KDocKnownTag.RETURN -> Return(parseStringToDocNode(tag.getContent(), externalDRIProvider))

‎dokka-subprojects/analysis-kotlin-symbols/src/main/kotlin/org/jetbrains/dokka/analysis/kotlin/symbols/kdoc/moduledocs/ModuleAndPackageDocumentationReader.kt‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import org.jetbrains.dokka.model.DPackage
1212
import org.jetbrains.dokka.model.SourceSetDependent
1313
import org.jetbrains.dokka.model.doc.*
1414
import org.jetbrains.dokka.model.doc.Deprecated
15+
import org.jetbrains.dokka.model.doc.Suppress
1516
import org.jetbrains.dokka.plugability.DokkaContext
1617
import org.jetbrains.dokka.plugability.plugin
1718
import org.jetbrains.dokka.plugability.querySingle
@@ -107,7 +108,7 @@ private class ContextModuleAndPackageDocumentationReader(
107108
is Receiver -> acc.copy(newRoot)
108109
is Constructor -> acc.copy(newRoot)
109110
is Deprecated -> acc.copy(newRoot)
110-
is org.jetbrains.dokka.model.doc.Suppress -> acc.copy(newRoot)
111+
is Suppress -> acc.copy(newRoot)
111112
}
112113
}
113114
}

‎dokka-subprojects/core/api/dokka-core.api‎

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3055,12 +3055,18 @@ public final class org/jetbrains/dokka/model/doc/P : org/jetbrains/dokka/model/d
30553055
}
30563056

30573057
public final class org/jetbrains/dokka/model/doc/Param : org/jetbrains/dokka/model/doc/NamedTagWrapper {
3058-
public fun <init> (Lorg/jetbrains/dokka/model/doc/DocTag;Ljava/lang/String;)V
3058+
public synthetic fun <init> (Lorg/jetbrains/dokka/model/doc/DocTag;Ljava/lang/String;)V
3059+
public fun <init> (Lorg/jetbrains/dokka/model/doc/DocTag;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;)V
3060+
public synthetic fun <init> (Lorg/jetbrains/dokka/model/doc/DocTag;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;ILkotlin/jvm/internal/DefaultConstructorMarker;)V
30593061
public final fun component1 ()Lorg/jetbrains/dokka/model/doc/DocTag;
30603062
public final fun component2 ()Ljava/lang/String;
3061-
public final fun copy (Lorg/jetbrains/dokka/model/doc/DocTag;Ljava/lang/String;)Lorg/jetbrains/dokka/model/doc/Param;
3063+
public final fun component3 ()Lorg/jetbrains/dokka/links/DRI;
3064+
public final synthetic fun copy (Lorg/jetbrains/dokka/model/doc/DocTag;Ljava/lang/String;)Lorg/jetbrains/dokka/model/doc/Param;
3065+
public final fun copy (Lorg/jetbrains/dokka/model/doc/DocTag;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;)Lorg/jetbrains/dokka/model/doc/Param;
30623066
public static synthetic fun copy$default (Lorg/jetbrains/dokka/model/doc/Param;Lorg/jetbrains/dokka/model/doc/DocTag;Ljava/lang/String;ILjava/lang/Object;)Lorg/jetbrains/dokka/model/doc/Param;
3067+
public static synthetic fun copy$default (Lorg/jetbrains/dokka/model/doc/Param;Lorg/jetbrains/dokka/model/doc/DocTag;Ljava/lang/String;Lorg/jetbrains/dokka/links/DRI;ILjava/lang/Object;)Lorg/jetbrains/dokka/model/doc/Param;
30633068
public fun equals (Ljava/lang/Object;)Z
3069+
public final fun getAddress ()Lorg/jetbrains/dokka/links/DRI;
30643070
public fun getName ()Ljava/lang/String;
30653071
public fun getRoot ()Lorg/jetbrains/dokka/model/doc/DocTag;
30663072
public fun hashCode ()I

‎dokka-subprojects/core/src/main/kotlin/org/jetbrains/dokka/model/doc/TagWrapper.kt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@ package org.jetbrains.dokka.model.doc
66

77
import org.jetbrains.dokka.links.DRI
88
import org.jetbrains.dokka.model.WithChildren
9+
import kotlin.Deprecated
910

1011
public sealed class TagWrapper : WithChildren<DocTag> {
1112
public abstract val root: DocTag
@@ -23,7 +24,13 @@ public data class Author(override val root: DocTag) : TagWrapper()
2324
public data class Version(override val root: DocTag) : TagWrapper()
2425
public data class Since(override val root: DocTag) : TagWrapper()
2526
public data class See(override val root: DocTag, override val name: String, val address: DRI?) : NamedTagWrapper()
26-
public data class Param(override val root: DocTag, override val name: String) : NamedTagWrapper()
27+
public data class Param(override val root: DocTag, override val name: String, val address: DRI? = null) : NamedTagWrapper() {
28+
@Deprecated("Binary compatibility", level = DeprecationLevel.HIDDEN)
29+
public constructor(root: DocTag, name: String) : this(root, name, null)
30+
31+
@Deprecated("Binary compatibility", level = DeprecationLevel.HIDDEN)
32+
public fun copy(root: DocTag, name: String = this.name): Param = Param(root, name, address = null)
33+
}
2734
public data class Return(override val root: DocTag) : TagWrapper()
2835
public data class Receiver(override val root: DocTag) : TagWrapper()
2936
public data class Constructor(override val root: DocTag) : TagWrapper()

‎dokka-subprojects/plugin-base/src/main/kotlin/org/jetbrains/dokka/base/translators/documentables/DescriptionSections.kt‎

Lines changed: 35 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,13 @@
55
package org.jetbrains.dokka.base.translators.documentables
66

77
import org.jetbrains.dokka.DokkaConfiguration
8+
import org.jetbrains.dokka.ExperimentalDokkaApi
89
import org.jetbrains.dokka.Platform
910
import org.jetbrains.dokka.base.transformers.documentables.InheritorsInfo
1011
import org.jetbrains.dokka.base.transformers.pages.tags.CustomTagContentProvider
1112
import org.jetbrains.dokka.links.DRI
12-
import org.jetbrains.dokka.links.PointingToDeclaration
13+
import org.jetbrains.dokka.links.PointingToContextParameters
14+
import org.jetbrains.dokka.links.PointingToGenericParameters
1315
import org.jetbrains.dokka.model.Documentable
1416
import org.jetbrains.dokka.model.SourceSetDependent
1517
import org.jetbrains.dokka.model.WithScope
@@ -113,9 +115,40 @@ internal fun PageContentBuilder.DocumentableContentBuilder.paramsSectionContent(
113115
val params = tags.withTypeNamed<Param>()
114116
if (params.isEmpty()) return
115117

118+
@OptIn(ExperimentalDokkaApi::class)
119+
val contextParams = params.mapValues {
120+
it.value.filterValues { param -> param.address?.target is PointingToContextParameters }
121+
}.filterValues { it.isNotEmpty() }
122+
val typeParams = params.mapValues {
123+
it.value.filterValues { param -> param.address?.target is PointingToGenericParameters }
124+
}.filterValues { it.isNotEmpty() }
125+
val otherParams = params - contextParams.keys - typeParams.keys
126+
127+
paramsSectionContent(
128+
sectionName = "Context Parameters",
129+
params = contextParams
130+
)
131+
132+
paramsSectionContent(
133+
sectionName = "Parameters",
134+
params = otherParams
135+
)
136+
137+
paramsSectionContent(
138+
sectionName = "Type Parameters",
139+
params = typeParams
140+
)
141+
}
142+
143+
internal fun PageContentBuilder.DocumentableContentBuilder.paramsSectionContent(
144+
sectionName: String,
145+
params: Map<String, SourceSetDependent<Param>>,
146+
) {
147+
if (params.isEmpty()) return
148+
116149
val availableSourceSets = params.availableSourceSets()
117150
tableSectionContentBlock(
118-
blockName = "Parameters",
151+
blockName = sectionName,
119152
kind = ContentKind.Parameters,
120153
sourceSets = availableSourceSets
121154
) {

0 commit comments

Comments
 (0)