Beautification and documentation.

3 files changed, 27 insertions, 5 deletions

diff --git a/src/Analysis/AnalysisEnvironment.kt b/src/Analysis/AnalysisEnvironment.kt
index d657ae4a..9fe90628 100644
--- a/src/Analysis/AnalysisEnvironment.kt
+++ b/src/Analysis/AnalysisEnvironment.kt
@@ -12,6 +12,12 @@ import org.jetbrains.jet.cli.jvm.*
 import com.intellij.openapi.util.*
 import org.jetbrains.jet.lang.descriptors.ModuleDescriptor
 
+/**
+ * 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
+ */
 public class AnalysisEnvironment(val messageCollector: MessageCollector, body: AnalysisEnvironment.() -> Unit = {}) : Disposable {
     val configuration = CompilerConfiguration();
 
@@ -20,6 +26,10 @@ public class AnalysisEnvironment(val messageCollector: MessageCollector, body: A
         body()
     }
 
+    /**
+     * Executes [processor] when analysis is complete.
+     * $processor is a function to receive compiler environment, module and context for symbol resolution
+     */
     public fun withContext<T>(processor: (JetCoreEnvironment, ModuleDescriptor, BindingContext) -> T): T {
         val environment = JetCoreEnvironment.createForProduction(this, configuration)
         val exhaust = environment.analyze(messageCollector)
diff --git a/src/Formats/MarkdownFormatService.kt b/src/Formats/MarkdownFormatService.kt
index 2e541113..9626f62c 100644
--- a/src/Formats/MarkdownFormatService.kt
+++ b/src/Formats/MarkdownFormatService.kt
@@ -1,5 +1,7 @@
 package org.jetbrains.dokka
 
+import org.jetbrains.dokka.DocumentationNode.Kind
+
 public class MarkdownFormatService(val locationService: LocationService,
                                    val signatureGenerator: SignatureGenerator) : FormatService {
     override val extension: String = "md"
@@ -15,9 +17,11 @@ public class MarkdownFormatService(val locationService: LocationService,
             appendln(node.doc.description)
             appendln()
             for (section in node.doc.sections) {
-                append("### ")
-                appendln(section.label)
-                appendln(section.text)
+                append("##### ")
+                append(section.label)
+                appendln()
+                append(section.text)
+                appendln()
             }
 
             if (node.members.any()) {
@@ -26,7 +30,11 @@ public class MarkdownFormatService(val locationService: LocationService,
                 appendln("|------|-----------|---------|")
                 for (member in node.members.sortBy { it.name }) {
                     val relativePath = locationService.relativeLocation(node, member, extension)
-                    append("|[${member.name}](${relativePath})")
+                    val displayName = when (member.kind) {
+                        Kind.Constructor -> "*.init*"
+                        else -> signatureGenerator.renderName(member).htmlEscape()
+                    }
+                    append("|[${displayName}](${relativePath})")
                     append("|`${signatureGenerator.render(member)}`")
                     append("|${member.doc.summary} ")
                     appendln("|")
@@ -34,4 +42,4 @@ public class MarkdownFormatService(val locationService: LocationService,
             }
         }
     }
-}
\ No newline at end of file
+}
diff --git a/src/Utilities/Html.kt b/src/Utilities/Html.kt
new file mode 100644
index 00000000..a4fd5fae
--- /dev/null
+++ b/src/Utilities/Html.kt
@@ -0,0 +1,4 @@
+package org.jetbrains.dokka
+
+fun String.htmlEscape() = replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+