aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
Diffstat
-rw-r--r--README.md19
-rw-r--r--core/src/main/kotlin/Kotlin/ContentBuilder.kt22
-rw-r--r--core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt12
-rw-r--r--core/src/test/kotlin/model/LinkTest.kt10
-rw-r--r--core/testdata/links/linkToConstantWithUnderscores.kt8
-rw-r--r--dokka-gradle-plugin/build.gradle1
-rw-r--r--dokka-gradle-plugin/src/main/kotlin/main.kt16
7 files changed, 68 insertions, 20 deletions
diff --git a/README.md b/README.md
index ed2f8975..f955a386 100644
--- a/README.md
+++ b/README.md
@@ -132,10 +132,17 @@ buildscript {
apply plugin: 'org.jetbrains.dokka'
```
-To configure plugin use dokka lambda in the root scope. For example:
+The plugin adds a task named "dokka" to the project. The available configuration
+options are shown below:
```groovy
dokka {
+ moduleName = 'data'
+ outputFormat = 'javadoc'
+ outputDirectory = "$buildDir/javadoc"
+ processConfigurations = ['compile', 'extra']
+ includes = ['packages.md', 'extra.md']
+ samples = ['samples/basic.kt', 'samples/advanced.kt']
linkMapping {
dir = "src/main/kotlin"
url = "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"
@@ -150,6 +157,16 @@ To get it generated use gradle `dokka` task
./gradlew dokka
```
+More dokka tasks can be added to a project like this:
+
+```groovy
+task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
+ outputFormat = 'javadoc'
+ outputDirectory = "$buildDir/javadoc"
+}
+```
+
+
Please see the [Dokka Gradle example project](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/dokka-gradle-example) for an example.
## Dokka Internals
diff --git a/core/src/main/kotlin/Kotlin/ContentBuilder.kt b/core/src/main/kotlin/Kotlin/ContentBuilder.kt
index e4ed3962..ea07acbc 100644
--- a/core/src/main/kotlin/Kotlin/ContentBuilder.kt
+++ b/core/src/main/kotlin/Kotlin/ContentBuilder.kt
@@ -48,27 +48,27 @@ fun buildContentTo(tree: MarkdownNode, target: ContentBlock, linkResolver: (Stri
MarkdownElementTypes.PARAGRAPH -> appendNodeWithChildren(ContentParagraph())
MarkdownElementTypes.INLINE_LINK -> {
- val label = node.child(MarkdownElementTypes.LINK_TEXT)?.child(MarkdownTokenTypes.TEXT)
+ val labelText = node.child(MarkdownElementTypes.LINK_TEXT)?.getLabelText()
val destination = node.child(MarkdownElementTypes.LINK_DESTINATION)
- if (label != null) {
+ if (labelText != null) {
if (destination != null) {
val link = ContentExternalLink(destination.text)
- link.append(ContentText(label.text))
+ link.append(ContentText(labelText))
parent.append(link)
} else {
- val link = ContentExternalLink(label.text)
- link.append(ContentText(label.text))
+ val link = ContentExternalLink(labelText)
+ link.append(ContentText(labelText))
parent.append(link)
}
}
}
MarkdownElementTypes.SHORT_REFERENCE_LINK,
MarkdownElementTypes.FULL_REFERENCE_LINK -> {
- val label = node.child(MarkdownElementTypes.LINK_LABEL)?.child(MarkdownTokenTypes.TEXT)
- if (label != null) {
- val link = linkResolver(label.text)
- val linkText = node.child(MarkdownElementTypes.LINK_TEXT)?.child(MarkdownTokenTypes.TEXT)
- link.append(ContentText(linkText?.text ?: label.text))
+ val labelText = node.child(MarkdownElementTypes.LINK_LABEL)?.getLabelText()
+ if (labelText != null) {
+ val link = linkResolver(labelText)
+ val linkText = node.child(MarkdownElementTypes.LINK_TEXT)?.getLabelText()
+ link.append(ContentText(linkText ?: labelText))
parent.append(link)
}
}
@@ -127,6 +127,8 @@ fun buildContentTo(tree: MarkdownNode, target: ContentBlock, linkResolver: (Stri
}
}
+private fun MarkdownNode.getLabelText() = children.filter { it.type == MarkdownTokenTypes.TEXT || it.type == MarkdownTokenTypes.EMPH }.joinToString("") { it.text }
+
private fun keepWhitespace(node: ContentNode) = node is ContentParagraph || node is ContentSection
fun buildInlineContentTo(tree: MarkdownNode, target: ContentBlock, linkResolver: (String) -> ContentBlock) {
diff --git a/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt b/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt
index 3a5769c9..7d39e5ac 100644
--- a/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt
+++ b/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt
@@ -19,6 +19,8 @@ import org.jetbrains.kotlin.psi.KtBlockExpression
import org.jetbrains.kotlin.psi.KtDeclarationWithBody
import org.jetbrains.kotlin.resolve.DescriptorToSourceUtils
import org.jetbrains.kotlin.resolve.DescriptorUtils
+import org.jetbrains.kotlin.resolve.annotations.argumentValue
+import org.jetbrains.kotlin.resolve.constants.StringValue
import org.jetbrains.kotlin.resolve.scopes.DescriptorKindFilter
import org.jetbrains.kotlin.resolve.scopes.ResolutionScope
import org.jetbrains.kotlin.resolve.scopes.getDescriptorsFiltered
@@ -43,7 +45,7 @@ class DescriptorDocumentationParser
if (kdoc == null) {
if (options.reportUndocumented && !descriptor.isDeprecated() &&
descriptor !is ValueParameterDescriptor && descriptor !is TypeParameterDescriptor &&
- descriptor !is PropertyAccessorDescriptor) {
+ descriptor !is PropertyAccessorDescriptor && !descriptor.isSuppressWarning()) {
logger.warn("No documentation for ${descriptor.signatureWithSourceLocation()}")
}
return Content.Empty to { node -> }
@@ -75,6 +77,14 @@ class DescriptorDocumentationParser
return content to { node -> }
}
+ private fun DeclarationDescriptor.isSuppressWarning() : Boolean {
+ val suppressAnnotation = annotations.findAnnotation(FqName(Suppress::class.qualifiedName!!))
+ return if (suppressAnnotation != null) {
+ @Suppress("UNCHECKED_CAST")
+ (suppressAnnotation.argumentValue("names") as List<StringValue>).any { it.value == "NOT_DOCUMENTED" }
+ } else containingDeclaration?.isSuppressWarning() ?: false
+ }
+
/**
* Special case for generating stdlib documentation (the Any class to which the override chain will resolve
* is not the same one as the Any class included in the source scope).
diff --git a/core/src/test/kotlin/model/LinkTest.kt b/core/src/test/kotlin/model/LinkTest.kt
index 3db1b90f..bcb1007c 100644
--- a/core/src/test/kotlin/model/LinkTest.kt
+++ b/core/src/test/kotlin/model/LinkTest.kt
@@ -25,6 +25,16 @@ public class LinkTest {
}
}
+ @Test fun linkToConstantWithUnderscores() {
+ verifyModel("testdata/links/linkToConstantWithUnderscores.kt") { model ->
+ with(model.members.single().members.single()) {
+ assertEquals("Foo", name)
+ assertEquals(DocumentationNode.Kind.Class, kind)
+ assertEquals("This is link to [MY_CONSTANT_VALUE -> CompanionObjectProperty:MY_CONSTANT_VALUE]", content.summary.toTestString())
+ }
+ }
+ }
+
@Test fun linkToQualifiedMember() {
verifyModel("testdata/links/linkToQualifiedMember.kt") { model ->
with(model.members.single().members.single()) {
diff --git a/core/testdata/links/linkToConstantWithUnderscores.kt b/core/testdata/links/linkToConstantWithUnderscores.kt
new file mode 100644
index 00000000..57011bfa
--- /dev/null
+++ b/core/testdata/links/linkToConstantWithUnderscores.kt
@@ -0,0 +1,8 @@
+/**
+ * This is link to [MY_CONSTANT_VALUE]
+ */
+class Foo {
+ companion object {
+ val MY_CONSTANT_VALUE = 0
+ }
+} \ No newline at end of file
diff --git a/dokka-gradle-plugin/build.gradle b/dokka-gradle-plugin/build.gradle
index 484c93c2..94786774 100644
--- a/dokka-gradle-plugin/build.gradle
+++ b/dokka-gradle-plugin/build.gradle
@@ -23,7 +23,6 @@ apply plugin: 'com.jfrog.bintray'
sourceCompatibility = 1.6
repositories {
- mavenLocal()
mavenCentral()
maven {
url 'http://oss.sonatype.org/content/repositories/snapshots'
diff --git a/dokka-gradle-plugin/src/main/kotlin/main.kt b/dokka-gradle-plugin/src/main/kotlin/main.kt
index 1fe0058f..476f7656 100644
--- a/dokka-gradle-plugin/src/main/kotlin/main.kt
+++ b/dokka-gradle-plugin/src/main/kotlin/main.kt
@@ -35,13 +35,13 @@ open class DokkaTask : DefaultTask() {
var outputFormat: String = "html"
var outputDirectory: String = ""
@Input
- var processConfigurations: ArrayList<String> = arrayListOf("compile")
+ var processConfigurations: List<Any?> = arrayListOf("compile")
@Input
- var includes: ArrayList<String> = arrayListOf()
+ var includes: List<Any?> = arrayListOf()
@Input
var linkMappings: ArrayList<LinkMapping> = arrayListOf()
@Input
- var samples: ArrayList<String> = arrayListOf()
+ var samples: List<Any?> = arrayListOf()
@Input
var jdkVersion: Int = 6
@@ -68,7 +68,7 @@ open class DokkaTask : DefaultTask() {
val classpath =
processConfigurations
- .map { allConfigurations?.getByName(it) ?: throw IllegalArgumentException("No configuration $it found") }
+ .map { allConfigurations?.getByName(it.toString()) ?: throw IllegalArgumentException("No configuration $it found") }
.flatMap { it }
if (sourceDirectories.isEmpty()) {
@@ -80,8 +80,8 @@ open class DokkaTask : DefaultTask() {
DokkaGradleLogger(logger),
classpath.map { it.absolutePath },
sourceDirectories.map { it.absolutePath },
- samples,
- includes,
+ samples.filterNotNull().map { project.file(it).absolutePath },
+ includes.filterNotNull().map { project.file(it).absolutePath },
moduleName,
DocumentationOptions(outputDirectory, outputFormat,
sourceLinks = linkMappings.map { SourceLinkDefinition(project.file(it.dir).absolutePath, it.url, it.suffix) },
@@ -97,7 +97,9 @@ open class DokkaTask : DefaultTask() {
@InputFiles
@SkipWhenEmpty
- fun getIncludedFiles() : FileCollection = project.files(getSourceDirectories().map { project.fileTree(it) })
+ fun getInputFiles() : FileCollection = project.files(getSourceDirectories().map { project.fileTree(it) }) +
+ project.files(includes) +
+ project.files(samples)
@OutputDirectory
fun getOutputDirectoryAsFile() : File = project.file(outputDirectory)
generated by cgit (git 2.46.0) at 2024-12-01 02:48:28 +0000