-
Notifications
You must be signed in to change notification settings - Fork 415
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Add an extension point for rendering custom doc tags * Iterate over documentable sourcesets when building custom tags * Extract a nested custom tags brief block into a separate method * Filter out tag content providers and make since kotlin brief a one-liner * Add padding to "Since Kotlin" block in brief description
- Loading branch information
1 parent
7be3ec0
commit ae9334f
Showing
15 changed files
with
210 additions
and
38 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
59 changes: 59 additions & 0 deletions
59
plugins/base/src/main/kotlin/transformers/pages/tags/CustomTagContentProvider.kt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,59 @@ | ||
| package org.jetbrains.dokka.base.transformers.pages.tags | ||
|
|
||
| import org.jetbrains.dokka.DokkaConfiguration.DokkaSourceSet | ||
| import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder | ||
| import org.jetbrains.dokka.model.doc.CustomTagWrapper | ||
| import org.jetbrains.dokka.model.doc.DocTag | ||
|
|
||
| /** | ||
| * Provides an ability to render custom doc tags | ||
| * | ||
| * Custom tags can be generated during build, for instance via transformers from converting an annotation | ||
| * (such as in [org.jetbrains.dokka.base.transformers.pages.annotations.SinceKotlinTransformer]) | ||
| * | ||
| * Also, custom tags can come from the kdoc itself, where "custom" is defined as unknown to the compiler/spec. | ||
| * `@property` and `@throws` are not custom tags - they are defined by the spec and have special meaning | ||
| * and separate blocks on the documentation page, it's clear how to render it. Whereas `@usesMathJax` is | ||
| * a custom tag - it's application/plugin specific and is not handled by dokka by default. | ||
| * | ||
| * Using this provider, we can map custom tags (such as `@usesMathJax`) and generate content for it that | ||
| * will be displayed on the pages. | ||
| */ | ||
| interface CustomTagContentProvider { | ||
|
|
||
| /** | ||
| * Whether this content provider supports given [CustomTagWrapper]. | ||
| * | ||
| * Tags can be filtered out either by name or by nested [DocTag] type | ||
| */ | ||
| fun isApplicable(customTag: CustomTagWrapper): Boolean | ||
|
|
||
| /** | ||
| * Full blown content description, most likely to be on a separate page | ||
| * dedicated to just one element (i.e one class/function), so any | ||
| * amount of detail should be fine. | ||
| */ | ||
| fun DocumentableContentBuilder.contentForDescription( | ||
| sourceSet: DokkaSourceSet, | ||
| customTag: CustomTagWrapper | ||
| ) {} | ||
|
|
||
| /** | ||
| * Brief comment section, usually displayed as a summary/preview. | ||
| * | ||
| * For instance, when listing all functions of a class on one page, | ||
| * it'll be too much to display complete documentation for each function. | ||
| * Instead, a small brief is shown for each one (i.e the first paragraph | ||
| * or some other important information) - the user can go to the dedicated | ||
| * page for more details if they find the brief interesting. | ||
| * | ||
| * Tag-wise, it would make sense to include `Since Kotlin`, since it's | ||
| * important information for the users of stdlib. It would make little | ||
| * sense to include `@usesMathjax` here, as this information seems | ||
| * to be more specific and detailed than is needed for a brief. | ||
| */ | ||
| fun DocumentableContentBuilder.contentForBrief( | ||
| sourceSet: DokkaSourceSet, | ||
| customTag: CustomTagWrapper | ||
| ) {} | ||
| } |
34 changes: 34 additions & 0 deletions
34
plugins/base/src/main/kotlin/transformers/pages/tags/SinceKotlinTagContentProvider.kt
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| package org.jetbrains.dokka.base.transformers.pages.tags | ||
|
|
||
| import org.jetbrains.dokka.DokkaConfiguration | ||
| import org.jetbrains.dokka.base.translators.documentables.PageContentBuilder.DocumentableContentBuilder | ||
| import org.jetbrains.dokka.model.doc.CustomTagWrapper | ||
| import org.jetbrains.dokka.pages.ContentKind | ||
| import org.jetbrains.dokka.pages.TextStyle | ||
|
|
||
| object SinceKotlinTagContentProvider : CustomTagContentProvider { | ||
|
|
||
| private const val SINCE_KOTLIN_TAG_NAME = "Since Kotlin" | ||
|
|
||
| override fun isApplicable(customTag: CustomTagWrapper) = customTag.name == SINCE_KOTLIN_TAG_NAME | ||
|
|
||
| override fun DocumentableContentBuilder.contentForDescription( | ||
| sourceSet: DokkaConfiguration.DokkaSourceSet, | ||
| customTag: CustomTagWrapper | ||
| ) { | ||
| group(sourceSets = setOf(sourceSet), kind = ContentKind.Comment, styles = setOf(TextStyle.Block)) { | ||
| header(4, customTag.name) | ||
| comment(customTag.root) | ||
| } | ||
| } | ||
|
|
||
| override fun DocumentableContentBuilder.contentForBrief( | ||
| sourceSet: DokkaConfiguration.DokkaSourceSet, | ||
| customTag: CustomTagWrapper | ||
| ) { | ||
| group(sourceSets = setOf(sourceSet), styles = setOf(TextStyle.InlineComment)) { | ||
| text(customTag.name + " ", styles = setOf(TextStyle.Bold)) | ||
| comment(customTag.root, styles = emptySet()) | ||
| } | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.