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(-) (limited to 'core') 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 (limited to 'core') 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