From bfd9ffd13ed6b6916790f5f0de5f9523db71b22e Mon Sep 17 00:00:00 2001 From: Dmitry Jemerov Date: Fri, 30 Jan 2015 17:59:15 +0100 Subject: load sections from KDoc PSI, not through Markdown extensions --- src/Kotlin/ContentBuilder.kt | 48 +++++++++++++++++--------------------------- 1 file changed, 18 insertions(+), 30 deletions(-) (limited to 'src/Kotlin/ContentBuilder.kt') diff --git a/src/Kotlin/ContentBuilder.kt b/src/Kotlin/ContentBuilder.kt index c943a505..95e08c92 100644 --- a/src/Kotlin/ContentBuilder.kt +++ b/src/Kotlin/ContentBuilder.kt @@ -9,10 +9,16 @@ import org.intellij.markdown.* import org.jetbrains.kotlin.psi.JetDeclarationWithBody import org.jetbrains.kotlin.psi.JetBlockExpression -public fun DocumentationBuilder.buildContent(tree: MarkdownNode, descriptor: DeclarationDescriptor): Content { +public fun DocumentationBuilder.buildContent(tree: MarkdownNode): Content { + val result = Content() + buildContentTo(tree, result) + return result +} + +public fun DocumentationBuilder.buildContentTo(tree: MarkdownNode, target: ContentNode) { // println(tree.toTestString()) val nodeStack = ArrayDeque() - nodeStack.push(Content()) + nodeStack.push(target) tree.visit {(node, processChildren) -> val parent = nodeStack.peek()!! @@ -47,22 +53,6 @@ public fun DocumentationBuilder.buildContent(tree: MarkdownNode, descriptor: Dec processChildren() parent.append(nodeStack.pop()) } - MarkdownTokenTypes.SECTION_ID -> { - if (parent !is ContentSection) { - val text = node.text.trimLeading("$").trim("{", "}") - val name = text.substringBefore(" ") - val params = text.substringAfter(" ") - when (name) { - "code" -> parent.append(functionBody(descriptor, params)) - } - } - } - MarkdownElementTypes.SECTION -> { - val label = node.child(MarkdownTokenTypes.SECTION_ID)?.let { it.text.trimLeading("$").trim("{", "}") } ?: "" - nodeStack.push(ContentSection(label)) - processChildren() - parent.append(nodeStack.pop()) - } MarkdownElementTypes.INLINE_LINK -> { val label = node.child(MarkdownElementTypes.LINK_TEXT)?.child(MarkdownTokenTypes.TEXT) val destination = node.child(MarkdownElementTypes.LINK_DESTINATION) @@ -88,7 +78,7 @@ public fun DocumentationBuilder.buildContent(tree: MarkdownNode, descriptor: Dec } MarkdownTokenTypes.WHITE_SPACE, MarkdownTokenTypes.EOL -> { - if (nodeStack.peek() is ContentParagraph && node.parent?.children?.last() != node) { + if (keepWhitespace(nodeStack.peek()) && node.parent?.children?.last() != node) { nodeStack.push(ContentText(node.text)) processChildren() parent.append(nodeStack.pop()) @@ -105,10 +95,7 @@ public fun DocumentationBuilder.buildContent(tree: MarkdownNode, descriptor: Dec parent.append(nodeStack.pop()) } MarkdownTokenTypes.COLON -> { - // TODO fix markdown parser - if (!isColonAfterSectionLabel(node)) { - parent.append(ContentText(node.text)) - } + parent.append(ContentText(node.text)) } MarkdownTokenTypes.DOUBLE_QUOTE, MarkdownTokenTypes.LT, @@ -120,9 +107,16 @@ public fun DocumentationBuilder.buildContent(tree: MarkdownNode, descriptor: Dec } } } - return nodeStack.pop() as Content } +private fun keepWhitespace(node: ContentNode) = node is ContentParagraph || node is ContentSection + +public fun DocumentationBuilder.buildInlineContentTo(tree: MarkdownNode, target: ContentNode) { + val inlineContent = tree.children.firstOrNull { it.type == MarkdownElementTypes.PARAGRAPH }?.children ?: listOf(tree) + inlineContent.forEach { + buildContentTo(it, target) + } +} fun DocumentationBuilder.functionBody(descriptor: DeclarationDescriptor, functionName: String): ContentNode { val scope = getResolutionScope(descriptor) @@ -176,9 +170,3 @@ private fun DocumentationBuilder.resolveInScope(functionName: String, scope: Jet return symbol } - -private fun isColonAfterSectionLabel(node: MarkdownNode): Boolean { - val parent = node.parent - return parent != null && parent.type == MarkdownElementTypes.SECTION && parent.children.size() >= 2 && - node == parent.children[1]; -} -- cgit From 0fac1d925b74f24002a4e1538088ce66c4b02cb9 Mon Sep 17 00:00:00 2001 From: Dmitry Jemerov Date: Fri, 30 Jan 2015 19:01:40 +0100 Subject: code review --- src/Formats/StructuredFormatService.kt | 21 +++++++++++---------- src/Kotlin/ContentBuilder.kt | 2 +- src/Kotlin/DocumentationBuilder.kt | 14 +++++++++----- src/Model/Content.kt | 24 ++++++++++++------------ src/Model/DocumentationNode.kt | 8 +------- test/src/model/CommentTest.kt | 20 ++++++++++---------- 6 files changed, 44 insertions(+), 45 deletions(-) (limited to 'src/Kotlin/ContentBuilder.kt') diff --git a/src/Formats/StructuredFormatService.kt b/src/Formats/StructuredFormatService.kt index fe127732..6ec75379 100644 --- a/src/Formats/StructuredFormatService.kt +++ b/src/Formats/StructuredFormatService.kt @@ -98,23 +98,24 @@ public abstract class StructuredFormatService(val locationService: LocationServi appendSectionWithSubject(it.getKey(), location, it.getValue(), to) } - for (section in node.content.sections) { - if (section.subjectName != null) continue - appendLine(to, formatStrong(formatText(section.label))) + for (section in node.content.sections.filter { it.subjectName == null }) { + appendLine(to, formatStrong(formatText(section.tag))) appendLine(to, formatText(location, section)) } } } } - fun appendSectionWithSubject(title: String, location: Location, parameterSections: List, to: StringBuilder) { + fun Content.getSectionsWithSubjects(): Map> = + sections.filter { it.subjectName != null }.groupBy { it.tag } + + fun appendSectionWithSubject(title: String, location: Location, subjectSections: List, to: StringBuilder) { appendHeader(to, title, 3) - parameterSections.forEach { - val parameterName = it.subjectName - if (parameterName != null) { - to.append(formatCode(parameterName)).append(" - ") - val formatted = formatText(location, it) - to.append(formatted) + subjectSections.forEach { + val subjectName = it.subjectName + if (subjectName != null) { + to.append(formatCode(subjectName)).append(" - ") + to.append(formatText(location, it)) appendLine(to) } } diff --git a/src/Kotlin/ContentBuilder.kt b/src/Kotlin/ContentBuilder.kt index 95e08c92..35beec54 100644 --- a/src/Kotlin/ContentBuilder.kt +++ b/src/Kotlin/ContentBuilder.kt @@ -112,7 +112,7 @@ public fun DocumentationBuilder.buildContentTo(tree: MarkdownNode, target: Conte private fun keepWhitespace(node: ContentNode) = node is ContentParagraph || node is ContentSection public fun DocumentationBuilder.buildInlineContentTo(tree: MarkdownNode, target: ContentNode) { - val inlineContent = tree.children.firstOrNull { it.type == MarkdownElementTypes.PARAGRAPH }?.children ?: listOf(tree) + val inlineContent = tree.children.singleOrNull { it.type == MarkdownElementTypes.PARAGRAPH }?.children ?: listOf(tree) inlineContent.forEach { buildContentTo(it, target) } diff --git a/src/Kotlin/DocumentationBuilder.kt b/src/Kotlin/DocumentationBuilder.kt index 053615bc..c0533437 100644 --- a/src/Kotlin/DocumentationBuilder.kt +++ b/src/Kotlin/DocumentationBuilder.kt @@ -41,13 +41,15 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati fun parseDocumentation(descriptor: DeclarationDescriptor): Content { val kdoc = findKDoc(descriptor) - val docText = kdoc?.getContent() ?: "" - val tree = parseMarkdown(docText) + if (kdoc == null) { + return Content.Empty + } + val tree = parseMarkdown(kdoc.getContent()) //println(tree.toTestString()) val content = buildContent(tree) if (kdoc is KDocSection) { - val tags = PsiTreeUtil.getChildrenOfType(kdoc, javaClass()) - tags?.forEach { + val tags = kdoc.getTags() + tags.forEach { if (it.getName() == "code") { content.append(functionBody(descriptor, it.getContent())) } else { @@ -61,11 +63,13 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati return content } + fun KDocSection.getTags(): Array = PsiTreeUtil.getChildrenOfType(this, javaClass()) ?: array() + fun displayName(sectionName: String?): String? = when(sectionName) { "param" -> "Parameters" "throws", "exception" -> "Exceptions" - else -> sectionName + else -> sectionName?.capitalize() } fun link(node: DocumentationNode, descriptor: DeclarationDescriptor) { diff --git a/src/Model/Content.kt b/src/Model/Content.kt index 2fae317d..e59037d2 100644 --- a/src/Model/Content.kt +++ b/src/Model/Content.kt @@ -1,5 +1,7 @@ package org.jetbrains.dokka +import kotlin.properties.Delegates + public abstract class ContentNode { val children = arrayListOf() @@ -32,7 +34,7 @@ public class ContentNodeLink(val node : DocumentationNode) : ContentBlock() public class ContentExternalLink(val href : String) : ContentBlock() public class ContentList() : ContentBlock() public class ContentListItem() : ContentBlock() -public class ContentSection(public val label: String, public val subjectName: String?) : ContentBlock() +public class ContentSection(public val tag: String, public val subjectName: String?) : ContentBlock() fun content(body: ContentNode.() -> Unit): ContentNode { val block = ContentBlock() @@ -62,22 +64,20 @@ public class Content() : ContentNode() { return section } - fun findSectionByName(name: String): ContentSection? = - sections.firstOrNull { it.label == name } - - fun getSectionsWithSubjects(): Map> = - sections.filter { it.subjectName != null }.groupBy { it.label } + fun findSectionByTag(tag: String): ContentSection? = + sections.firstOrNull { tag.equalsIgnoreCase(it.tag) } public val summary: ContentNode get() = children.firstOrNull() ?: ContentEmpty - public val description: ContentNode get() { + public val description: ContentNode by Delegates.lazy { val descriptionNodes = children.drop(1) if (descriptionNodes.isEmpty()) { - return ContentEmpty + ContentEmpty + } else { + val result = ContentSection("Description", null) + result.children.addAll(descriptionNodes) + result } - val result = ContentSection("\$description", null) - result.children.addAll(descriptionNodes) - return result } override fun equals(other: Any?): Boolean { @@ -93,7 +93,7 @@ public class Content() : ContentNode() { override fun toString(): String { if (sections.isEmpty()) return "" - return sections.joinToString() + return (listOf(summary, description) + sections).joinToString() } val isEmpty: Boolean diff --git a/src/Model/DocumentationNode.kt b/src/Model/DocumentationNode.kt index 3a61b8fb..c3700069 100644 --- a/src/Model/DocumentationNode.kt +++ b/src/Model/DocumentationNode.kt @@ -8,13 +8,7 @@ public open class DocumentationNode(val name: String, private val references = LinkedHashSet() - - public val summary: ContentNode get() { - val contentSection = content.summary - if (contentSection != null) - return contentSection - return ContentNode.empty - } + public val summary: ContentNode get() = content.summary public val owner: DocumentationNode? get() = references(DocumentationReference.Kind.Owner).singleOrNull()?.to diff --git a/test/src/model/CommentTest.kt b/test/src/model/CommentTest.kt index 353336d6..98585b18 100644 --- a/test/src/model/CommentTest.kt +++ b/test/src/model/CommentTest.kt @@ -68,8 +68,8 @@ public class CommentTest { with(model.members.single().members.single()) { assertEquals("Summary", content.summary.toTestString()) assertEquals(1, content.sections.count()) - with (content.findSectionByName("one")!!) { - assertEquals("one", label) + with (content.findSectionByTag("one")!!) { + assertEquals("One", tag) assertEquals("", toTestString()) } } @@ -81,8 +81,8 @@ public class CommentTest { with(model.members.single().members.single()) { assertEquals("Summary", content.summary.toTestString()) assertEquals(1, content.sections.count()) - with (content.findSectionByName("one")!!) { - assertEquals("one", label) + with (content.findSectionByTag("one")!!) { + assertEquals("One", tag) assertEquals("section one", toTestString()) } } @@ -94,12 +94,12 @@ public class CommentTest { with(model.members.single().members.single()) { assertEquals("Summary", content.summary.toTestString()) assertEquals(2, content.sections.count()) - with (content.findSectionByName("one")!!) { - assertEquals("one", label) + with (content.findSectionByTag("one")!!) { + assertEquals("One", tag) assertEquals("section one", toTestString()) } - with (content.findSectionByName("two")!!) { - assertEquals("two", label) + with (content.findSectionByTag("two")!!) { + assertEquals("Two", tag) assertEquals("section two", toTestString()) } } @@ -111,8 +111,8 @@ public class CommentTest { with(model.members.single().members.single()) { assertEquals("Summary", content.summary.toTestString()) assertEquals(1, content.sections.count()) - with (content.findSectionByName("one")!!) { - assertEquals("one", label) + with (content.findSectionByTag("one")!!) { + assertEquals("One", tag) assertEquals("""line one line two""", toTestString()) } -- cgit