1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
|
dokka [](https://teamcity.jetbrains.com/viewType.html?buildTypeId=Kotlin_Dokka_DokkaAntMavenGradle&branch_KotlinTools_Dokka=%3Cdefault%3E&tab=buildTypeStatusDiv) [  ](https://bintray.com/kotlin/dokka/dokka/_latestVersion)
=====
Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java.
Just like Kotlin itself, Dokka fully supports mixed-language Java/Kotlin projects. It understands
standard Javadoc comments in Java files and [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in Kotlin files,
and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown.
## Using Dokka
### Using the Command Line
To run Dokka from the command line, download the [Dokka jar](https://github.com/Kotlin/dokka/releases/download/0.9.7/dokka-fatjar.jar).
To generate documentation, run the following command:
java -jar dokka-fatjar.jar <source directories> <arguments>
Dokka supports the following command line arguments:
* `output` - the output directory where the documentation is generated
* `format` - the output format:
* `html` - HTML (default)
* `markdown` - Markdown
* `jekyll` - Markdown adapted for Jekyll sites
* `javadoc` - Javadoc (showing how the project can be accessed from Java)
* `classpath` - list of directories or .jar files to include in the classpath (used for resolving references)
* `samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag)
* `module` - the name of the module being documented (used as the root directory of the generated documentation)
* `include` - names of files containing the documentation for the module and individual packages
* `nodeprecated` - if set, deprecated elements are not included in the generated documentation
### Using the Ant task
The Ant task definition is also contained in the dokka-fatjar.jar referenced above. Here's an example of using it:
```xml
<project name="Dokka" default="document">
<typedef resource="dokka-antlib.xml" classpath="dokka-fatjar.jar"/>
<target name="document">
<dokka src="src" outputdir="doc" modulename="myproject"/>
</target>
</project>
```
The Ant task supports the following attributes:
* `outputdir` - the output directory where the documentation is generated
* `outputformat` - the output format (see the list of supported formats above)
* `classpath` - list of directories or .jar files to include in the classpath (used for resolving references)
* `samples` - list of directories containing sample code (documentation for those directories is not generated but declarations from them can be referenced using the `@sample` tag)
* `modulename` - the name of the module being documented (used as the root directory of the generated documentation)
* `include` - names of files containing the documentation for the module and individual packages
* `skipdeprecated` - if set, deprecated elements are not included in the generated documentation
### Using the Maven plugin
The Maven plugin is available in JCenter. You need to add the JCenter repository to the list of plugin repositories if it's not there:
```xml
<pluginRepositories>
<pluginRepository>
<id>jcenter</id>
<name>JCenter</name>
<url>https://jcenter.bintray.com/</url>
</pluginRepository>
</pluginRepositories>
```
Minimal maven configuration is
```xml
<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:
```xml
<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>
```
Please see the [Dokka Maven example project](https://github.com/JetBrains/kotlin-examples/tree/master/maven/dokka-maven-example) for an example.
### Using the Gradle plugin
```groovy
buildscript {
repositories {
mavenLocal()
jcenter()
}
dependencies {
classpath "org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}"
}
}
apply plugin: 'org.jetbrains.dokka'
```
The plugin adds a task named "dokka" to the project. The available configuration
options are shown below:
```groovy
dokka {
moduleName = 'data'
outputFormat = 'javadoc'
outputDirectory = "$buildDir/javadoc"
processConfigurations = ['compile', 'extra']
includes = ['packages.md', 'extra.md']
samples = ['samples/basic.kt', 'samples/advanced.kt']
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
```bash
./gradlew dokka
```
More dokka tasks can be added to a project like this:
```groovy
task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
outputFormat = 'javadoc'
outputDirectory = "$buildDir/javadoc"
}
```
Please see the [Dokka Gradle example project](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/dokka-gradle-example) for an example.
## Dokka Internals
### 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:
1. Member - reference means that target is member of the source, form tree.
2. Detail - reference means that target describes source in more details, form tree.
3. 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:
```kotlin
val signatureGenerator = KotlinSignatureGenerator()
val locationService = FoldersLocationService(arguments.outputDir)
val markdown = JekyllFormatService(locationService, signatureGenerator)
val generator = FileGenerator(signatureGenerator, locationService, markdown)
generator.generate(documentation)
```
## Building Dokka
Dokka is built with Gradle. To build it, use `./gradlew build`.
Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run Dokka.
|
