From bd39691072ba1a4fb02ac945efa14d1c6276245e Mon Sep 17 00:00:00 2001 From: James Strachan Date: Tue, 17 Apr 2012 08:37:56 +0100 Subject: [PATCH] fixed up apidoc comments and fixed bug in kdoc where macros would not be used if there was whitespace before the @ --- libraries/stdlib/src/kotlin/Preconditions.kt | 14 ++--- .../jetbrains/kotlin/doc/model/KotlinModel.kt | 54 ++++++++++--------- 2 files changed, 37 insertions(+), 31 deletions(-) diff --git a/libraries/stdlib/src/kotlin/Preconditions.kt b/libraries/stdlib/src/kotlin/Preconditions.kt index e618dfb9647..87281b77b35 100644 --- a/libraries/stdlib/src/kotlin/Preconditions.kt +++ b/libraries/stdlib/src/kotlin/Preconditions.kt @@ -6,7 +6,7 @@ object Assertions { } /** -* Throws an [[AssertionError]] with specified *message* if the *value* is false +* Throws an [[AssertionError]] with an optional *message* if the *value* is false * and runtime assertions have been enabled on the JVM using the *-ea* JVM option. */ public inline fun assert(value: Boolean, message: Any = "Assertion failed") { @@ -18,7 +18,7 @@ public inline fun assert(value: Boolean, message: Any = "Assertion failed") { } /** - * Throws an [[AssertionError]] with specified *message* if the *value* is false + * Throws an [[AssertionError]] with the specified *lazyMessage* if the *value* is false * and runtime assertions have been enabled on the JVM using the *-ea* JVM option. */ public inline fun assert(value: Boolean, lazyMessage: () -> String) { @@ -31,7 +31,7 @@ public inline fun assert(value: Boolean, lazyMessage: () -> String) { } /** - * Throws an [[IllegalArgumentException]] with specified *message* if the *value* is false. + * Throws an [[IllegalArgumentException]] with an optional *message* if the *value* is false. * * @includeFunctionBody ../../test/PreconditionsTest.kt failingRequireWithMessage */ @@ -42,7 +42,7 @@ public inline fun require(value: Boolean, message: Any = "Failed requirement"): } /** - * Throws an [[IllegalArgumentException]] with specified *message* if the *value* is false. + * Throws an [[IllegalArgumentException]] with the *lazyMessage* if the *value* is false. * * @includeFunctionBody ../../test/PreconditionsTest.kt failingRequireWithLazyMessage */ @@ -68,7 +68,7 @@ public inline fun requireNotNull(value: T?, message: Any = "Required value w } /** - * Throws an [[IllegalStateException]] with specified *message* if the *value* is false. + * Throws an [[IllegalStateException]] with an optional *message* if the *value* is false. * * @includeFunctionBody ../../test/PreconditionsTest.kt failingCheckWithMessage */ @@ -79,9 +79,9 @@ public inline fun check(value: Boolean, message: Any = "Check failed"): Unit { } /** - * Throws an [[IllegalStateException]] with specified *message* if the *value* is false. + * Throws an [[IllegalStateException]] with the *lazyMessage* if the *value* is false. * - * @includeFunctionBody ../../test/PreconditionsTest.kt failingCheckWithMessage + * @includeFunctionBody ../../test/PreconditionsTest.kt failingCheckWithLazyMessage */ public inline fun check(value: Boolean, lazyMessage: () -> String): Unit { if (!value) { diff --git a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt index b63454a7042..c0037162ef7 100644 --- a/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt +++ b/libraries/tools/kdoc/src/main/kotlin/org/jetbrains/kotlin/doc/model/KotlinModel.kt @@ -485,30 +485,7 @@ class KModel(var context: BindingContext, val config: KDocConfig) { text = text.trimLeading("* ") if (text == "*") text = "" } - // lets check for javadoc style @ tags and macros - if (text.startsWith("@")) { - val remaining = text.substring(1) - val macro = "includeFunctionBody" - if (remaining.startsWith(macro)) { - val next = remaining.substring(macro.length()).trim() - val words = next.split("\\s") - // TODO we could default the test function name to match that of the - // source code function if folks adopted a convention of naming the test method after the - // method its acting as a demo/test for - if (words != null && words.size > 1) { - val includeFile = words[0].sure() - val fnName = words[1].sure() - val content = findFunctionInclude(psiElement, includeFile, fnName) - if (content != null) { - text = highlighter.highlight(content) - } else { - warning("could not find function $fnName in file $includeFile from source file ${psiElement.getContainingFile()}") - } - } - } else { - warning("Unknown kdoc macro @$remaining") - } - } + text = processMacros(text, psiElement) buffer.append(text) } return buffer.toString() ?: "" @@ -519,6 +496,35 @@ class KModel(var context: BindingContext, val config: KDocConfig) { return "" } + protected fun processMacros(textWithWhitespace: String, psiElement: PsiElement): String { + val text = textWithWhitespace.trim() + // lets check for javadoc style @ tags and macros + if (text.startsWith("@")) { + val remaining = text.substring(1) + val macro = "includeFunctionBody" + if (remaining.startsWith(macro)) { + val next = remaining.substring(macro.length()).trim() + val words = next.split("\\s") + // TODO we could default the test function name to match that of the + // source code function if folks adopted a convention of naming the test method after the + // method its acting as a demo/test for + if (words != null && words.size > 1) { + val includeFile = words[0].sure() + val fnName = words[1].sure() + val content = findFunctionInclude(psiElement, includeFile, fnName) + if (content != null) { + return highlighter.highlight(content) + } else { + warning("could not find function $fnName in file $includeFile from source file ${psiElement.getContainingFile()}") + } + } + } else { + warning("Unknown kdoc macro @$remaining") + } + } + return textWithWhitespace + } + protected fun findFunctionInclude(psiElement: PsiElement, includeFile: String, functionName: String): String? { var dir = psiElement.getContainingFile()?.getParent() if (dir != null) {