commit	36f4b916bc956d8f5c9f6b55d295ea9a69c9f0bc	[log] [tgz]
author	Dmitry Jemerov <yole@jetbrains.com>	Wed Oct 28 15:23:50 2015 +0100
committer	Dmitry Jemerov <yole@jetbrains.com>	Thu Oct 29 11:57:24 2015 +0100
tree	cab9e34dec64cce5cea97bbf9f1bd5e276ac42be
parent	78455025203b911c855f7cfc0d75270dd7351199 [diff]

tree: cab9e34dec64cce5cea97bbf9f1bd5e276ac42be

README.md

dokka

Dokka is documentation engine for Kotlin, performing the same function as javadoc for Java.

NOTE: It is work in progress both on compiler side and this tool. Do not base your business on it. Yet.

Documentation Model

Dokka uses Kotlin-as-a-service technology to build code model, then processes it into documentation model. Documentation model is graph of items describing code elements such as classes, packages, functions, etc.

Each node has semantic attached, e.g. Value:name -> Type:String means that some value name is of type String.

Each reference between nodes also has semantic attached, and there are three of them:

Member - reference means that target is member of the source, form tree.
Detail - reference means that target describes source in more details, form tree.
Link - any link to any other node, free form.

Member & Detail has reverse Owner reference, while Link's back reference is also Link.

Nodes that are Details of other nodes cannot have Members.

Rendering Docs

When we have documentation model, we can render docs in various formats, languages and layouts. We have some core services:

FormatService -- represents output format
LocationService -- represents folder and file layout
SignatureGenerator -- represents target language by generating class/function/package signatures from model

Basically, given the documentation as a model, we do this:

    val signatureGenerator = KotlinSignatureGenerator() 
    val locationService = FoldersLocationService(arguments.outputDir)
    val markdown = JekyllFormatService(locationService, signatureGenerator)
    val generator = FileGenerator(signatureGenerator, locationService, markdown)
    generator.generate(documentation)

Samples

Dokka docs are built with Dokka. Yes, we bootstrap and dogfood :)

Roadmap

Formats

Documentation can be generated in various mark-up formats.

Text -- plain text format
HTML -- html format, suitable for local browsing
MD -- markdown format, and optional Jekyll extension for your GitHub pages

Locations

Place documentation in different file structure. All links are relative regardless of structure.

Single File -- all documentation is placed in the single file
Single Folder -- all documentation is in same folder, files are generated per entity
Folder Tree -- folders are mirroring package/class/method structure, files are leaf elements

Languages

Output symbol declarations in different languages.

Kotlin
Java
JavaScript

Features

Support JavaDoc in Java and Kotlin files
Support KDoc in Kotlin files

KDoc

KDoc is a flavour of markdown with symbol processing extensions.

[name] - link to name (markdown style)
$name - link to name (Kotlin string interpolation style), or ${java.lang.String} for longer references
$name: - named section, optionally bound to symbol name, e.g. param doc
${code reference} -- include content of a symbol denoted by reference, e.g. code example

Building

Build only dokka

ant fatjar

Build dokka and maven plugin

ant install-fj
cd maven-plugin
mvn install

Build dokka and install maven plugin (do not require maven installed)

ant build-and-install

Using Maven plugin

Minimal maven configuration is

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>${dokka.version}</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>dokka</goal>
            </goals>
        </execution>
    </executions>
</plugin>

by default files will be generated in target/dokka

Configuring source links mapping

<plugin>
    <groupId>org.jetbrains.dokka</groupId>
    <artifactId>dokka-maven-plugin</artifactId>
    <version>${dokka.version}</version>
    <executions>
        <execution>
            <phase>pre-site</phase>
            <goals>
                <goal>dokka</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <sourceLinks>
            <link>
                <dir>${project.basedir}/src/main/kotlin</dir>
                <url>http://github.com/me/myrepo</url>
            </link>
        </sourceLinks>
    </configuration>
</plugin>

Using Gradle plugin

buildscript {
    repositories {
        mavenLocal()
        jcenter()
    }
    dependencies {
        classpath "org.jetbrains.dokka:dokka-gradle-plugin:0.1-SNAPSHOT"
    }
}

apply plugin: 'org.jetbrains.dokka'

To configure plugin use dokka lambda in the root scope. For example:

dokka {
    linkMapping {
        dir = "src/main/kotlin"
        url = "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"
        suffix = "#L"
    }
}

To get it generated use gradle dokka task

./gradlew dokka