diff options
Diffstat (limited to 'core/src')
44 files changed, 1192 insertions, 964 deletions
diff --git a/core/src/main/kotlin/Analysis/AnalysisEnvironment.kt b/core/src/main/kotlin/Analysis/AnalysisEnvironment.kt index a5e35a0e..b0c39ee5 100644 --- a/core/src/main/kotlin/Analysis/AnalysisEnvironment.kt +++ b/core/src/main/kotlin/Analysis/AnalysisEnvironment.kt @@ -57,7 +57,7 @@ import java.io.File * $messageCollector: required by compiler infrastructure and will receive all compiler messages * $body: optional and can be used to configure environment without creating local variable */ -public class AnalysisEnvironment(val messageCollector: MessageCollector) : Disposable { +class AnalysisEnvironment(val messageCollector: MessageCollector) : Disposable { val configuration = CompilerConfiguration(); init { @@ -119,14 +119,14 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector) : Dispo /** * Classpath for this environment. */ - public val classpath: List<File> + val classpath: List<File> get() = configuration.jvmClasspathRoots /** * Adds list of paths to classpath. * $paths: collection of files to add */ - public fun addClasspath(paths: List<File>) { + fun addClasspath(paths: List<File>) { configuration.addJvmClasspathRoots(paths) } @@ -134,14 +134,14 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector) : Dispo * Adds path to classpath. * $path: path to add */ - public fun addClasspath(path: File) { + fun addClasspath(path: File) { configuration.addJvmClasspathRoot(path) } /** * List of source roots for this environment. */ - public val sources: List<String> + val sources: List<String> get() = configuration.get(CommonConfigurationKeys.CONTENT_ROOTS) ?.filterIsInstance<KotlinSourceRoot>() ?.map { it.path } ?: emptyList() @@ -150,25 +150,25 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector) : Dispo * Adds list of paths to source roots. * $list: collection of files to add */ - public fun addSources(list: List<String>) { + fun addSources(list: List<String>) { list.forEach { configuration.add(CommonConfigurationKeys.CONTENT_ROOTS, contentRootFromPath(it)) } } - public fun addRoots(list: List<ContentRoot>) { + fun addRoots(list: List<ContentRoot>) { configuration.addAll(CommonConfigurationKeys.CONTENT_ROOTS, list) } /** * Disposes the environment and frees all associated resources. */ - public override fun dispose() { + override fun dispose() { Disposer.dispose(this) } } -public fun contentRootFromPath(path: String): ContentRoot { +fun contentRootFromPath(path: String): ContentRoot { val file = File(path) return if (file.extension == "java") JavaSourceRoot(file, null) else KotlinSourceRoot(path) } diff --git a/core/src/main/kotlin/Formats/FormatDescriptor.kt b/core/src/main/kotlin/Formats/FormatDescriptor.kt index 0c7ca794..e384f223 100644 --- a/core/src/main/kotlin/Formats/FormatDescriptor.kt +++ b/core/src/main/kotlin/Formats/FormatDescriptor.kt @@ -3,7 +3,7 @@ package org.jetbrains.dokka.Formats import org.jetbrains.dokka.* import kotlin.reflect.KClass -public interface FormatDescriptor { +interface FormatDescriptor { val formatServiceClass: KClass<out FormatService>? val outlineServiceClass: KClass<out OutlineFormatService>? val generatorServiceClass: KClass<out Generator> diff --git a/core/src/main/kotlin/Formats/FormatService.kt b/core/src/main/kotlin/Formats/FormatService.kt index 73e54956..aa4e925c 100644 --- a/core/src/main/kotlin/Formats/FormatService.kt +++ b/core/src/main/kotlin/Formats/FormatService.kt @@ -7,7 +7,7 @@ package org.jetbrains.dokka * * [HtmlFormatService] – outputs documentation to HTML format * * [MarkdownFormatService] – outputs documentation in Markdown format */ -public interface FormatService { +interface FormatService { /** Returns extension for output files */ val extension: String diff --git a/core/src/main/kotlin/Formats/HtmlFormatService.kt b/core/src/main/kotlin/Formats/HtmlFormatService.kt index d513e41f..f78439ba 100644 --- a/core/src/main/kotlin/Formats/HtmlFormatService.kt +++ b/core/src/main/kotlin/Formats/HtmlFormatService.kt @@ -6,11 +6,11 @@ import java.io.File import java.nio.file.Path import java.nio.file.Paths -public open class HtmlFormatService @Inject constructor(@Named("folders") locationService: LocationService, - signatureGenerator: LanguageService, - val templateService: HtmlTemplateService) +open class HtmlFormatService @Inject constructor(@Named("folders") locationService: LocationService, + signatureGenerator: LanguageService, + val templateService: HtmlTemplateService) : StructuredFormatService(locationService, signatureGenerator, "html"), OutlineFormatService { - override public fun formatText(text: String): String { + override fun formatText(text: String): String { return text.htmlEscape() } diff --git a/core/src/main/kotlin/Formats/HtmlTemplateService.kt b/core/src/main/kotlin/Formats/HtmlTemplateService.kt index ae42a31b..13587b05 100644 --- a/core/src/main/kotlin/Formats/HtmlTemplateService.kt +++ b/core/src/main/kotlin/Formats/HtmlTemplateService.kt @@ -2,12 +2,12 @@ package org.jetbrains.dokka import java.nio.file.Path -public interface HtmlTemplateService { +interface HtmlTemplateService { fun appendHeader(to: StringBuilder, title: String?, basePath: Path) fun appendFooter(to: StringBuilder) companion object { - public fun default(css: String? = null): HtmlTemplateService { + fun default(css: String? = null): HtmlTemplateService { return object : HtmlTemplateService { override fun appendFooter(to: StringBuilder) { to.appendln("</BODY>") diff --git a/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt b/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt index 870347ab..f869bc75 100644 --- a/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt +++ b/core/src/main/kotlin/Formats/KotlinWebsiteFormatService.kt @@ -2,7 +2,7 @@ package org.jetbrains.dokka import com.google.inject.Inject -public class KotlinWebsiteFormatService @Inject constructor(locationService: LocationService, +class KotlinWebsiteFormatService @Inject constructor(locationService: LocationService, signatureGenerator: LanguageService) : JekyllFormatService(locationService, signatureGenerator, "html") { private var needHardLineBreaks = false @@ -13,7 +13,7 @@ public class KotlinWebsiteFormatService @Inject constructor(locationService: Loc to.appendln("layout: api") } - override public fun formatBreadcrumbs(items: Iterable<FormatLink>): String { + override fun formatBreadcrumbs(items: Iterable<FormatLink>): String { items.drop(1) if (items.count() > 1) { @@ -25,7 +25,7 @@ public class KotlinWebsiteFormatService @Inject constructor(locationService: Loc return "" } - override public fun formatCode(code: String): String = if (code.length > 0) "<code>$code</code>" else "" + override fun formatCode(code: String): String = if (code.length > 0) "<code>$code</code>" else "" override fun formatStrikethrough(text: String): String = "<s>$text</s>" @@ -106,7 +106,7 @@ public class KotlinWebsiteFormatService @Inject constructor(locationService: Loc to.appendln("\n</td>") } - override public fun appendBlockCode(to: StringBuilder, line: String, language: String) { + override fun appendBlockCode(to: StringBuilder, line: String, language: String) { if (language.isNotEmpty()) { super.appendBlockCode(to, line, language) } else { diff --git a/core/src/main/kotlin/Formats/MarkdownFormatService.kt b/core/src/main/kotlin/Formats/MarkdownFormatService.kt index 07202b7e..4e16b1a8 100644 --- a/core/src/main/kotlin/Formats/MarkdownFormatService.kt +++ b/core/src/main/kotlin/Formats/MarkdownFormatService.kt @@ -3,16 +3,16 @@ package org.jetbrains.dokka import com.google.inject.Inject -public open class MarkdownFormatService +open class MarkdownFormatService @Inject constructor(locationService: LocationService, signatureGenerator: LanguageService, linkExtension: String = "md") : StructuredFormatService(locationService, signatureGenerator, "md", linkExtension) { - override public fun formatBreadcrumbs(items: Iterable<FormatLink>): String { + override fun formatBreadcrumbs(items: Iterable<FormatLink>): String { return items.map { formatLink(it) }.joinToString(" / ") } - override public fun formatText(text: String): String { + override fun formatText(text: String): String { return text.htmlEscape() } @@ -27,19 +27,19 @@ public open class MarkdownFormatService return text.htmlEscape() } - override public fun formatCode(code: String): String { + override fun formatCode(code: String): String { return "`$code`" } - override public fun formatUnorderedList(text: String): String = text + "\n" - override public fun formatOrderedList(text: String): String = text + "\n" + override fun formatUnorderedList(text: String): String = text + "\n" + override fun formatOrderedList(text: String): String = text + "\n" override fun formatListItem(text: String, kind: ListKind): String { val itemText = if (text.endsWith("\n")) text else text + "\n" return if (kind == ListKind.Unordered) "* $itemText" else "1. $itemText" } - override public fun formatStrong(text: String): String { + override fun formatStrong(text: String): String { return "**$text**" } @@ -55,7 +55,7 @@ public open class MarkdownFormatService return "[$text]($href)" } - override public fun appendLine(to: StringBuilder, text: String) { + override fun appendLine(to: StringBuilder, text: String) { to.appendln(text) } @@ -63,19 +63,19 @@ public open class MarkdownFormatService // no anchors in Markdown } - override public fun appendParagraph(to: StringBuilder, text: String) { + override fun appendParagraph(to: StringBuilder, text: String) { to.appendln() to.appendln(text) to.appendln() } - override public fun appendHeader(to: StringBuilder, text: String, level: Int) { + override fun appendHeader(to: StringBuilder, text: String, level: Int) { appendLine(to) appendLine(to, "${"#".repeat(level)} $text") appendLine(to) } - override public fun appendBlockCode(to: StringBuilder, line: String, language: String) { + override fun appendBlockCode(to: StringBuilder, line: String, language: String) { appendLine(to) to.appendln("``` ${language}") to.appendln(line) diff --git a/core/src/main/kotlin/Formats/OutlineService.kt b/core/src/main/kotlin/Formats/OutlineService.kt index 6626cf51..3c31ba57 100644 --- a/core/src/main/kotlin/Formats/OutlineService.kt +++ b/core/src/main/kotlin/Formats/OutlineService.kt @@ -5,14 +5,14 @@ import java.io.File /** * Service for building the outline of the package contents. */ -public interface OutlineFormatService { +interface OutlineFormatService { fun getOutlineFileName(location: Location): File - public fun appendOutlineHeader(location: Location, node: DocumentationNode, to: StringBuilder) - public fun appendOutlineLevel(to: StringBuilder, body: () -> Unit) + fun appendOutlineHeader(location: Location, node: DocumentationNode, to: StringBuilder) + fun appendOutlineLevel(to: StringBuilder, body: () -> Unit) /** Appends formatted outline to [StringBuilder](to) using specified [location] */ - public fun appendOutline(location: Location, to: StringBuilder, nodes: Iterable<DocumentationNode>) { + fun appendOutline(location: Location, to: StringBuilder, nodes: Iterable<DocumentationNode>) { for (node in nodes) { appendOutlineHeader(location, node, to) if (node.members.any()) { diff --git a/core/src/main/kotlin/Formats/StructuredFormatService.kt b/core/src/main/kotlin/Formats/StructuredFormatService.kt index 324f156a..1d464396 100644 --- a/core/src/main/kotlin/Formats/StructuredFormatService.kt +++ b/core/src/main/kotlin/Formats/StructuredFormatService.kt @@ -11,9 +11,9 @@ enum class ListKind { } abstract class StructuredFormatService(locationService: LocationService, - val languageService: LanguageService, - override val extension: String, - val linkExtension: String = extension) : FormatService { + val languageService: LanguageService, + override val extension: String, + val linkExtension: String = extension) : FormatService { val locationService: LocationService = locationService.withExtension(linkExtension) abstract fun appendBlockCode(to: StringBuilder, line: String, language: String) @@ -51,49 +51,51 @@ abstract class StructuredFormatService(locationService: LocationService, return nodes.map { formatText(location, it, listKind) }.joinToString("") } - open fun formatText(location: Location, content: ContentNode, listKind: ListKind = ListKind.Unordered): String { - return StringBuilder().apply { - when (content) { - is ContentText -> append(formatText(content.text)) - is ContentSymbol -> append(formatSymbol(content.text)) - is ContentKeyword -> append(formatKeyword(content.text)) - is ContentIdentifier -> append(formatIdentifier(content.text, content.kind)) - is ContentNonBreakingSpace -> append(formatNonBreakingSpace()) - is ContentSoftLineBreak -> append(formatSoftLineBreak()) - is ContentIndentedSoftLineBreak -> append(formatIndentedSoftLineBreak()) - is ContentEntity -> append(formatEntity(content.text)) - is ContentStrong -> append(formatStrong(formatText(location, content.children))) - is ContentStrikethrough -> append(formatStrikethrough(formatText(location, content.children))) - is ContentCode -> append(formatCode(formatText(location, content.children))) - is ContentEmphasis -> append(formatEmphasis(formatText(location, content.children))) - is ContentUnorderedList -> append(formatUnorderedList(formatText(location, content.children, ListKind.Unordered))) - is ContentOrderedList -> append(formatOrderedList(formatText(location, content.children, ListKind.Ordered))) - is ContentListItem -> append(formatListItem(formatText(location, content.children), listKind)) - - is ContentNodeLink -> { - val node = content.node - val linkTo = if (node != null) locationHref(location, node) else "#" - val linkText = formatText(location, content.children) - if (linkTo == ".") { - append(linkText) - } else { - append(formatLink(linkText, linkTo)) - } + fun formatText(location: Location, content: ContentNode, listKind: ListKind = ListKind.Unordered): String { + return StringBuilder().apply { formatText(location, content, this, listKind) }.toString() + } + + open fun formatText(location: Location, content: ContentNode, to: StringBuilder, listKind: ListKind = ListKind.Unordered) { + when (content) { + is ContentText -> to.append(formatText(content.text)) + is ContentSymbol -> to.append(formatSymbol(content.text)) + is ContentKeyword -> to.append(formatKeyword(content.text)) + is ContentIdentifier -> to.append(formatIdentifier(content.text, content.kind)) + is ContentNonBreakingSpace -> to.append(formatNonBreakingSpace()) + is ContentSoftLineBreak -> to.append(formatSoftLineBreak()) + is ContentIndentedSoftLineBreak -> to.append(formatIndentedSoftLineBreak()) + is ContentEntity -> to.append(formatEntity(content.text)) + is ContentStrong -> to.append(formatStrong(formatText(location, content.children))) + is ContentStrikethrough -> to.append(formatStrikethrough(formatText(location, content.children))) + is ContentCode -> to.append(formatCode(formatText(location, content.children))) + is ContentEmphasis -> to.append(formatEmphasis(formatText(location, content.children))) + is ContentUnorderedList -> to.append(formatUnorderedList(formatText(location, content.children, ListKind.Unordered))) + is ContentOrderedList -> to.append(formatOrderedList(formatText(location, content.children, ListKind.Ordered))) + is ContentListItem -> to.append(formatListItem(formatText(location, content.children), listKind)) + + is ContentNodeLink -> { + val node = content.node + val linkTo = if (node != null) locationHref(location, node) else "#" + val linkText = formatText(location, content.children) + if (linkTo == ".") { + to.append(linkText) + } else { + to.append(formatLink(linkText, linkTo)) } - is ContentExternalLink -> { - val linkText = formatText(location, content.children) - if (content.href == ".") { - append(linkText) - } else { - append(formatLink(linkText, content.href)) - } + } + is ContentExternalLink -> { + val linkText = formatText(location, content.children) + if (content.href == ".") { + to.append(linkText) + } else { + to.append(formatLink(linkText, content.href)) } - is ContentParagraph -> appendParagraph(this, formatText(location, content.children)) - is ContentBlockCode -> appendBlockCode(this, formatText(location, content.children), content.language) - is ContentHeading -> appendHeader(this, formatText(location, content.children), content.level) - is ContentBlock -> append(formatText(location, content.children)) } - }.toString() + is ContentParagraph -> appendParagraph(to, formatText(location, content.children)) + is ContentBlockCode -> appendBlockCode(to, formatText(location, content.children), content.language) + is ContentHeading -> appendHeader(to, formatText(location, content.children), content.level) + is ContentBlock -> to.append(formatText(location, content.children)) + } } open fun link(from: DocumentationNode, to: DocumentationNode): FormatLink = link(from, to, extension) @@ -103,51 +105,15 @@ abstract class StructuredFormatService(locationService: LocationService, } fun locationHref(from: Location, to: DocumentationNode): String { - val topLevelPage = to.references(DocumentationReference.Kind.TopLevelPage).singleOrNull()?.to + val topLevelPage = to.references(RefKind.TopLevelPage).singleOrNull()?.to if (topLevelPage != null) { return from.relativePathTo(locationService.location(topLevelPage), to.name) } return from.relativePathTo(locationService.location(to)) } - fun appendDocumentation(location: Location, to: StringBuilder, overloads: Iterable<DocumentationNode>) { - val breakdownBySummary = overloads.groupByTo(LinkedHashMap()) { node -> node.content } - - if (breakdownBySummary.size == 1) { - formatOverloadGroup(breakdownBySummary.values.single(), location, to) - } - else { - for ((summary, items) in breakdownBySummary) { - appendAsOverloadGroup(to) { - formatOverloadGroup(items, location, to) - } - } - } - } - - private fun formatOverloadGroup(items: MutableList<DocumentationNode>, location: Location, to: StringBuilder) { - items.forEach { - val rendered = languageService.render(it) - appendAsSignature(to, rendered) { - to.append(formatCode(formatText(location, rendered))) - it.appendSourceLink(to) - } - it.appendOverrides(to) - it.appendDeprecation(location, to) - } - // All items have exactly the same documentation, so we can use any item to render it - val item = items.first() - item.details(DocumentationNode.Kind.OverloadGroupNote).forEach { - to.append(formatText(location, it.content)) - } - to.append(formatText(location, item.content.summary)) - appendDescription(location, to, item) - appendLine(to) - appendLine(to) - } - private fun DocumentationNode.isModuleOrPackage(): Boolean = - kind == DocumentationNode.Kind.Module || kind == DocumentationNode.Kind.Package + kind == NodeKind.Module || kind == NodeKind.Package protected open fun appendAsSignature(to: StringBuilder, node: ContentNode, block: () -> Unit) { block() @@ -157,94 +123,218 @@ abstract class StructuredFormatService(locationService: LocationService, block() } - fun appendDescription(location: Location, to: StringBuilder, node: DocumentationNode) { - if (node.content.description != ContentEmpty) { - appendLine(to, formatText(location, node.content.description)) - appendLine(to) - } - node.content.getSectionsWithSubjects().forEach { - appendSectionWithSubject(it.key, location, it.value, to) - } + fun Content.getSectionsWithSubjects(): Map<String, List<ContentSection>> = + sections.filter { it.subjectName != null }.groupBy { it.tag } - for (section in node.content.sections.filter { it.subjectName == null }) { - appendLine(to, formatStrong(formatText(section.tag))) - appendLine(to, formatText(location, section)) + private fun ContentNode.signatureToText(location: Location): String { + return if (this is ContentBlock && this.isEmpty()) { + "" + } else { + val signatureAsCode = ContentCode() + signatureAsCode.append(this) + formatText(location, signatureAsCode) } } - fun Content.getSectionsWithSubjects(): Map<String, List<ContentSection>> = - sections.filter { it.subjectName != null }.groupBy { it.tag } + open inner class PageBuilder(val location: Location, val to: StringBuilder, val nodes: Iterable<DocumentationNode>) { + open fun build() { + val breakdownByLocation = nodes.groupBy { node -> + formatBreadcrumbs(node.path.filterNot { it.name.isEmpty() }.map { link(node, it) }) + } - fun appendSectionWithSubject(title: String, location: Location, subjectSections: List<ContentSection>, to: StringBuilder) { - appendHeader(to, title, 3) - subjectSections.forEach { - val subjectName = it.subjectName - if (subjectName != null) { - appendAnchor(to, subjectName) - to.append(formatCode(subjectName)).append(" - ") - to.append(formatText(location, it)) + for ((breadcrumbs, items) in breakdownByLocation) { + appendLine(to, breadcrumbs) appendLine(to) + appendLocation(items.filter { it.kind != NodeKind.ExternalClass }) } } - } - private fun DocumentationNode.appendOverrides(to: StringBuilder) { - overrides.forEach { |