From 556c71529248153014f9adc0865b1632a8c0436c Mon Sep 17 00:00:00 2001 From: ingo Date: Sun, 3 Jan 2016 19:06:17 +0100 Subject: mavenLocal() in dependencies can mess up generated gradle libraries in IntelliJ project --- dokka-gradle-plugin/build.gradle | 1 - 1 file changed, 1 deletion(-) 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' -- cgit From 97b5672ae2ef645c53e9c783dc494860a1eed800 Mon Sep 17 00:00:00 2001 From: ingo Date: Tue, 5 Jan 2016 23:44:52 +0100 Subject: Annotating functions or classes `@Suppress("NOT_DOCUMENTED")` will suppress warnings about missing documentation --- core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt b/core/src/main/kotlin/Kotlin/DescriptorDocumentationParser.kt index b7705ec9..8a15e9bf 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).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). -- cgit From ddd22fc7652f468f57c5a9dca380743eea53be5d Mon Sep 17 00:00:00 2001 From: ingo Date: Wed, 6 Jan 2016 13:39:54 +0100 Subject: Linking to a target with underscores did not work For example, in a link like [MY_VALUE], the link would only try to resolve the text "MY" until the first underscore. Since the markdown parser parses the link label as [TEXT:MY, EMPH:_, TEXT:VALUE], using the first TEXT child node is not sufficient. --- core/src/main/kotlin/Kotlin/ContentBuilder.kt | 22 ++++++++++++---------- core/src/test/kotlin/model/LinkTest.kt | 10 ++++++++++ .../links/linkToConstantWithUnderscores.kt | 8 ++++++++ 3 files changed, 30 insertions(+), 10 deletions(-) create mode 100644 core/testdata/links/linkToConstantWithUnderscores.kt diff --git a/core/src/main/kotlin/Kotlin/ContentBuilder.kt b/core/src/main/kotlin/Kotlin/ContentBuilder.kt index 1a6ffb98..39e8d8ce 100644 --- a/core/src/main/kotlin/Kotlin/ContentBuilder.kt +++ b/core/src/main/kotlin/Kotlin/ContentBuilder.kt @@ -48,27 +48,27 @@ public fun buildContentTo(tree: MarkdownNode, target: ContentBlock, linkResolver 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 @@ public fun buildContentTo(tree: MarkdownNode, target: ContentBlock, linkResolver } } +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 public fun buildInlineContentTo(tree: MarkdownNode, target: ContentBlock, linkResolver: (String) -> ContentBlock) { diff --git a/core/src/test/kotlin/model/LinkTest.kt b/core/src/test/kotlin/model/LinkTest.kt index c30e1c10..ac49cae6 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 -- cgit From fa871ac4602474164374009f56fbc8c3a533b504 Mon Sep 17 00:00:00 2001 From: ingo Date: Wed, 6 Jan 2016 16:25:34 +0100 Subject: gradle plugin: The "includes" and "samples" properties now accept relative file names and the list-typed properties are now more robust. --- README.md | 19 ++++++++++++++++++- dokka-gradle-plugin/src/main/kotlin/main.kt | 12 ++++++------ 2 files changed, 24 insertions(+), 7 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/dokka-gradle-plugin/src/main/kotlin/main.kt b/dokka-gradle-plugin/src/main/kotlin/main.kt index 28600a6b..c214a08e 100644 --- a/dokka-gradle-plugin/src/main/kotlin/main.kt +++ b/dokka-gradle-plugin/src/main/kotlin/main.kt @@ -34,13 +34,13 @@ public open class DokkaTask : DefaultTask() { var outputFormat: String = "html" var outputDirectory: String = "" @Input - var processConfigurations: ArrayList = arrayListOf("compile") + var processConfigurations: List = arrayListOf("compile") @Input - var includes: ArrayList = arrayListOf() + var includes: List = arrayListOf() @Input var linkMappings: ArrayList = arrayListOf() @Input - var samples: ArrayList = arrayListOf() + var samples: List = arrayListOf() fun linkMapping(closure: Closure) { val mapping = LinkMapping() @@ -65,7 +65,7 @@ public 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()) { @@ -77,8 +77,8 @@ public 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, outputDirectory, outputFormat, -- cgit From fc0f3f7574198851be009dd62c720b8372344c95 Mon Sep 17 00:00:00 2001 From: ingo Date: Wed, 6 Jan 2016 18:22:49 +0100 Subject: gradle plugin: up-to-date status did not consider include and sample files --- dokka-gradle-plugin/src/main/kotlin/main.kt | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/dokka-gradle-plugin/src/main/kotlin/main.kt b/dokka-gradle-plugin/src/main/kotlin/main.kt index c214a08e..ecdeac78 100644 --- a/dokka-gradle-plugin/src/main/kotlin/main.kt +++ b/dokka-gradle-plugin/src/main/kotlin/main.kt @@ -95,7 +95,9 @@ public 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) -- cgit