From 18399493263820cf6098603025802ddf862f1920 Mon Sep 17 00:00:00 2001
From: Ilya Ryzhenkov <orangy@jetbrains.com>
Date: Mon, 22 Dec 2014 09:50:17 +0200
Subject: Document some types in Dokka and fix to make them work.

---
 src/Formats/FormatService.kt           | 16 ++++++++++++++++
 src/Formats/HtmlFormatService.kt       |  8 ++++++++
 src/Formats/MarkdownFormatService.kt   |  8 ++++++++
 src/Formats/StructuredFormatService.kt |  5 +++++
 4 files changed, 37 insertions(+)

(limited to 'src/Formats')

diff --git a/src/Formats/FormatService.kt b/src/Formats/FormatService.kt
index 9af74590..bb6da985 100644
--- a/src/Formats/FormatService.kt
+++ b/src/Formats/FormatService.kt
@@ -1,10 +1,26 @@
 package org.jetbrains.dokka
 
+/**
+ * Abstract representation of a formatting service used to output documentation in desired format
+ *
+ * Bundled Formatters:
+ * * [HtmlFormatService] – outputs documentation to HTML format
+ * * [MarkdownFormatService] – outputs documentation in Markdown format
+ * * [TextFormatService] – outputs documentation in Text format
+ */
 public trait FormatService {
+    /** Returns extension for output files */
     val extension: String
+
+    /** Appends formatted content to [StringBuilder](to) using specified [location] */
     fun appendNodes(location: Location, to: StringBuilder, nodes: Iterable<DocumentationNode>)
+
+    /** Appends formatted outline to [StringBuilder](to) using specified [location] */
     fun appendOutline(location: Location, to: StringBuilder, nodes: Iterable<DocumentationNode>)
 }
 
+/** Format content to [String] using specified [location] */
 fun FormatService.format(location: Location, nodes: Iterable<DocumentationNode>): String = StringBuilder { appendNodes(location, this, nodes) }.toString()
+
+/** Format outline to [String] using specified [location] */
 fun FormatService.formatOutline(location: Location, nodes: Iterable<DocumentationNode>): String = StringBuilder { appendOutline(location, this, nodes) }.toString()
\ No newline at end of file
diff --git a/src/Formats/HtmlFormatService.kt b/src/Formats/HtmlFormatService.kt
index c337b69b..48291b48 100644
--- a/src/Formats/HtmlFormatService.kt
+++ b/src/Formats/HtmlFormatService.kt
@@ -97,6 +97,14 @@ public open class HtmlFormatService(locationService: LocationService,
         return "<code>${code.htmlEscape()}</code>"
     }
 
+    override fun formatList(text: String): String {
+        return "<ul>${text}</ul>"
+    }
+
+    override fun formatListItem(text: String): String {
+        return "<li>${text}</li>"
+    }
+
     override fun formatBreadcrumbs(items: Iterable<FormatLink>): String {
         return items.map { formatLink(it) }.joinToString("&nbsp;/&nbsp;")
     }
diff --git a/src/Formats/MarkdownFormatService.kt b/src/Formats/MarkdownFormatService.kt
index 8f9699c2..9849c674 100644
--- a/src/Formats/MarkdownFormatService.kt
+++ b/src/Formats/MarkdownFormatService.kt
@@ -30,6 +30,14 @@ public open class MarkdownFormatService(locationService: LocationService,
         return "`$code`"
     }
 
+    override public fun formatList(text: String): String {
+        return text
+    }
+
+    override fun formatListItem(text: String): String {
+        return "* $text"
+    }
+
     override public fun formatStrong(text: String): String {
         return "**$text**"
     }
diff --git a/src/Formats/StructuredFormatService.kt b/src/Formats/StructuredFormatService.kt
index 740f6b6a..08b7e55d 100644
--- a/src/Formats/StructuredFormatService.kt
+++ b/src/Formats/StructuredFormatService.kt
@@ -30,6 +30,8 @@ public abstract class StructuredFormatService(val locationService: LocationServi
     public abstract fun formatStrong(text: String): String
     public abstract fun formatEmphasis(text: String): String
     public abstract fun formatCode(code: String): String
+    public abstract fun formatList(text: String): String
+    public abstract fun formatListItem(text: String): String
     public abstract fun formatBreadcrumbs(items: Iterable<FormatLink>): String
 
     open fun formatText(location: Location, nodes: Iterable<ContentNode>): String {
@@ -46,6 +48,9 @@ public abstract class StructuredFormatService(val locationService: LocationServi
                 is ContentStrong -> append(formatStrong(formatText(location, content.children)))
                 is ContentCode -> append(formatCode(formatText(location, content.children)))
                 is ContentEmphasis -> append(formatEmphasis(formatText(location, content.children)))
+                is ContentList -> append(formatList(formatText(location, content.children)))
+                is ContentListItem -> append(formatListItem(formatText(location, content.children)))
+
                 is ContentNodeLink -> {
                     val linkTo = locationService.relativeLocation(location, content.node, extension)
                     val linkText = formatText(location, content.children)
-- 
cgit