Document some types in Dokka and fix to make them work.

13 files changed, 112 insertions, 20 deletions

diff --git a/lib/markdown.jar b/lib/markdown.jar
index 03449ef7..026f517f 100644
--- a/lib/markdown.jar
+++ b/lib/markdown.jar
diff --git a/src/Analysis/AnalysisEnvironment.kt b/src/Analysis/AnalysisEnvironment.kt
index f5a8287b..cc0e7184 100644
--- a/src/Analysis/AnalysisEnvironment.kt
+++ b/src/Analysis/AnalysisEnvironment.kt
@@ -15,9 +15,11 @@ import org.jetbrains.jet.lang.resolve.lazy.ResolveSession
 
 /**
  * Kotlin as a service entry point
+ *
  * Configures environment, analyses files and provides facilities to perform code processing without emitting bytecode
- * $messageCollector is required by compiler infrastructure and will receive all compiler messages
- * $body is optional and can be used to configure environment without creating local variable
+ *
+ * $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, body: AnalysisEnvironment.() -> Unit = {}) : Disposable {
     val configuration = CompilerConfiguration();
@@ -29,7 +31,7 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector, body: A
 
     /**
      * Executes [processor] when analysis is complete.
-     * $processor is a function to receive compiler environment, module and context for symbol resolution
+     * $processor: function to receive compiler environment, module and context for symbol resolution
      */
     public fun withContext<T>(processor: (JetCoreEnvironment, ResolveSession) -> T): T {
         val environment = JetCoreEnvironment.createForProduction(this, configuration, EnvironmentConfigFiles.JVM_CONFIG_FILES)
@@ -40,7 +42,7 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector, body: A
 
     /**
      * Executes [processor] when analysis is complete.
-     * $processor is a function to receive compiler module and context for symbol resolution
+     * $processor: function to receive compiler module and context for symbol resolution
      */
     public fun withContext<T>(processor: (ResolveSession) -> T): T {
         return withContext { environment, session -> processor(session) }
@@ -48,7 +50,7 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector, body: A
 
     /**
      * Streams files into [processor] and returns a stream of its results
-     * $processor is a function to receive context for symbol resolution and file for processing
+     * $processor: function to receive context for symbol resolution and file for processing
      */
     public fun streamFiles<T>(processor: (ResolveSession, JetFile) -> T): Stream<T> {
         return withContext { environment, session ->
@@ -58,7 +60,7 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector, body: A
 
     /**
      * Runs [processor] for each file and collects its results into single list
-     * $processor is a function to receive context for symbol resolution and file for processing
+     * $processor: function to receive context for symbol resolution and file for processing
      */
     public fun processFiles<T>(processor: (ResolveSession, JetFile) -> T): List<T> {
         return withContext { environment, session ->
@@ -68,7 +70,7 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector, body: A
 
     /**
      * Runs [processor] for each file and collects its results into single list
-     * $processor is a function to receive context for symbol resolution and file for processing
+     * $processor: is a function to receive context for symbol resolution and file for processing
      */
     public fun processFilesFlat<T>(processor: (ResolveSession, JetFile) -> List<T>): List<T> {
         return withContext { environment, session ->
@@ -84,7 +86,7 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector, body: A
 
     /**
      * Adds list of paths to classpath.
-     * $paths collection of paths to add
+     * $paths: collection of files to add
      */
     public fun addClasspath(paths: List<File>) {
         configuration.addAll(JVMConfigurationKeys.CLASSPATH_KEY, paths)
@@ -92,7 +94,7 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector, body: A
 
     /**
      * Adds path to classpath.
-     * $path path to add
+     * $path: path to add
      */
     public fun addClasspath(path: File) {
         configuration.add(JVMConfigurationKeys.CLASSPATH_KEY, path)
@@ -106,7 +108,7 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector, body: A
 
     /**
      * Adds list of paths to source roots.
-     * $list collection of files to add
+     * $list: collection of files to add
      */
     public fun addSources(list: List<String>) {
         configuration.addAll(CommonConfigurationKeys.SOURCE_ROOTS_KEY, list)
diff --git a/src/Analysis/CommentsAPI.kt b/src/Analysis/CommentsAPI.kt
index 215f3e98..5f3f6283 100644
--- a/src/Analysis/CommentsAPI.kt
+++ b/src/Analysis/CommentsAPI.kt
@@ -5,6 +5,11 @@ import org.jetbrains.jet.lang.resolve.*
 import org.jetbrains.jet.kdoc.psi.api.*
 import org.jetbrains.jet.lang.psi.*
 
+/**
+ * Retrieves PSI elements representing documentation from the [DeclarationDescriptor]
+ *
+ * $$receiver: [DeclarationDescriptor] to get documentation nodes from
+ */
 fun DeclarationDescriptor.getDocumentationElements(): List<KDoc> {
     val psiElement = DescriptorToSourceUtils.descriptorToDeclaration(this)
     if (psiElement == null)
@@ -17,6 +22,9 @@ fun DeclarationDescriptor.getDocumentationElements(): List<KDoc> {
             .reverse() // make reversed list
 }
 
+/**
+ * Extracts text from KDoc, removes comment symbols and trims whitespace
+ */
 fun KDoc?.extractText(): String {
     if (this == null)
         return ""
@@ -27,7 +35,7 @@ fun KDoc?.extractText(): String {
     return lines.map {
         val comment = it.trim().dropWhile { it == '/' || it == '*' }
         (if (comment.endsWith("*/"))
-            comment.substring(0, comment.length - 2)
+            comment.substring(0, comment.length() - 2)
         else
             comment).trim()
     }.join("\n")
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)
diff --git a/src/Kotlin/ContentBuilder.kt b/src/Kotlin/ContentBuilder.kt
index 462e886e..0c82a522 100644
--- a/src/Kotlin/ContentBuilder.kt
+++ b/src/Kotlin/ContentBuilder.kt
@@ -26,7 +26,7 @@ public fun DocumentationBuilder.buildContent(tree: MarkdownNode, descriptor: Dec
                 parent.append(nodeStack.pop())
             }
             MarkdownElementTypes.LIST_ITEM -> {
-                nodeStack.push(ContentBlock())
+                nodeStack.push(ContentListItem())
                 processChildren()
                 parent.append(nodeStack.pop())
             }
@@ -60,12 +60,26 @@ public fun DocumentationBuilder.buildContent(tree: MarkdownNode, descriptor: Dec
                 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)
+                if (label != null) {
+                    if (destination != null) {
+                        val link = ContentExternalLink(destination.text)
+                        link.append(ContentText(label.text))
+                        parent.append(link)
+                    } else {
+                        val link = ContentExternalLink(label.text)
+                        link.append(ContentText(label.text))
+                        parent.append(link)
+                    }
+                }
+            }
             MarkdownElementTypes.SHORT_REFERENCE_LINK -> {
-                val label = node.child(MarkdownElementTypes.LINK_LABEL)
-                val target = label?.child(MarkdownTokenTypes.TEXT)
-                if (target != null) {
-                    val link = ContentExternalLink(target.text)
-                    link.append(ContentText(target.text))
+                val label = node.child(MarkdownElementTypes.LINK_LABEL)?.child(MarkdownTokenTypes.TEXT)
+                if (label != null) {
+                    val link = ContentExternalLink(label.text)
+                    link.append(ContentText(label.text))
                     parent.append(link)
                 }
             }
diff --git a/src/Kotlin/DocumentationBuilder.kt b/src/Kotlin/DocumentationBuilder.kt
index c2d28312..7d38480a 100644
--- a/src/Kotlin/DocumentationBuilder.kt
+++ b/src/Kotlin/DocumentationBuilder.kt
@@ -338,6 +338,9 @@ class DocumentationBuilder(val session: ResolveSession, val options: Documentati
 
         }
 
+        if ("." !in reference)
+            return null
+
         val names = reference.split('.')
         val result = names.fold<String, DeclarationDescriptor?>(context) {(nextContext, name) ->
             nextContext?.let { resolveReference(it, name) }
diff --git a/src/Kotlin/KotlinLanguageService.kt b/src/Kotlin/KotlinLanguageService.kt
index c7fabda9..c9275879 100644
--- a/src/Kotlin/KotlinLanguageService.kt
+++ b/src/Kotlin/KotlinLanguageService.kt
@@ -11,6 +11,9 @@ import org.jetbrains.dokka.ContentNode
 import org.jetbrains.dokka
 import org.jetbrains.dokka.ContentText
 
+/**
+ * Implements [LanguageService] and provides rendering of symbols in Kotlin language
+ */
 class KotlinLanguageService : LanguageService {
     override fun render(node: DocumentationNode): ContentNode {
         return dokka.content {
diff --git a/src/Languages/LanguageService.kt b/src/Languages/LanguageService.kt
index 0f1a1d26..191f12c4 100644
--- a/src/Languages/LanguageService.kt
+++ b/src/Languages/LanguageService.kt
@@ -14,10 +14,8 @@ trait LanguageService {
     /**
      * Renders [node] as a named representation in the target language
      *
-     * See also [google](http://google.com)
-     *
      * $node: A [DocumentationNode] to render
-     * $returns: [String] which is a string representation of the node
+     * $returns: [String] which is a string representation of the node's name
      */
     fun renderName(node: DocumentationNode) : String
 }
diff --git a/src/Locations/LocationService.kt b/src/Locations/LocationService.kt
index 3c3ed3e1..cb0a5670 100644
--- a/src/Locations/LocationService.kt
+++ b/src/Locations/LocationService.kt
@@ -2,22 +2,48 @@ package org.jetbrains.dokka
 
 import java.io.File
 
+/**
+ * Represents locations in the documentation in the form of [path](File).
+ *
+ * Locations are provided by [LocationService.location] function.
+ *
+ * $file: [File] for this location
+ * $path: [String] representing path of this location
+ */
 public data class Location(val file: File) {
     public val path : String
         get() = file.path
 }
 
+/**
+ * Provides means of retrieving locations for [DocumentationNode](documentation nodes)
+ *
+ * `LocationService` determines where documentation for particular node should be generated
+ *
+ * * [FoldersLocationService] – represent packages and types as folders, members as files in those folders.
+ * * [SingleFolderLocationService] – all documentation is generated into single folder using fully qualified names
+ * for file names.
+ */
 public trait LocationService {
+    /**
+     * Calculates location for particular node in output structure
+     */
     fun location(node: DocumentationNode): Location
 }
 
 
 public fun escapeUri(path: String): String = path.replace('<', '-').replace('>', '-')
 
+/**
+ * Returns relative location between two nodes. Used for relative links in documentation.
+ */
 fun LocationService.relativeLocation(owner: DocumentationNode, node: DocumentationNode, extension: String): Location {
     return relativeLocation(location(owner), node, extension)
 }
 
+/**
+ * Returns relative location between base location and a node. Used for relative links in documentation.
+ */
 fun LocationService.relativeLocation(owner: Location, node: DocumentationNode, extension: String): Location {
     val ownerFolder = owner.file.getParentFile()!!
     val memberPath = location(node).file.appendExtension(extension)
diff --git a/src/Model/Content.kt b/src/Model/Content.kt
index 794faf50..e1c1ef78 100644
--- a/src/Model/Content.kt
+++ b/src/Model/Content.kt
@@ -32,6 +32,7 @@ public class ContentBlockCode() : ContentBlock()
 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) : ContentBlock()
 
 fun content(body: ContentNode.() -> Unit): ContentNode {