README.md
1dokka
2=====
3
4**_Note_: This is Google's fork of Dokka, customized for [Android API reference docs](https://developer.android.com/reference/)
5on [developer.android.com](https://developer.android.com/) and other Google products.**
6
7Dokka is a documentation engine for Kotlin, performing the same function as javadoc for Java.
8Just like Kotlin itself, Dokka fully supports mixed-language Java/Kotlin projects. It understands
9standard Javadoc comments in Java files and [KDoc comments](https://kotlinlang.org/docs/reference/kotlin-doc.html) in Kotlin files,
10and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown.
11
12## Using Dokka
13
14### Using the Gradle plugin
15
16```groovy
17buildscript {
18 repositories {
19 jcenter()
20 }
21
22 dependencies {
23 classpath "org.jetbrains.dokka:dokka-gradle-plugin:${dokka_version}"
24 }
25}
26
27apply plugin: 'org.jetbrains.dokka'
28```
29
30The plugin adds a task named "dokka" to the project.
31
32Minimal dokka configuration:
33
34```groovy
35dokka {
36 outputFormat = 'html'
37 outputDirectory = "$buildDir/javadoc"
38}
39```
40
41[Output formats](#output_formats)
42
43The available configuration options are shown below:
44
45```groovy
46dokka {
47 moduleName = 'data'
48 outputFormat = 'html'
49 outputDirectory = "$buildDir/javadoc"
50
51 // These tasks will be used to determine source directories and classpath
52 kotlinTasks {
53 defaultKotlinTasks() + [':some:otherCompileKotlin', project("another").compileKotlin]
54 }
55
56 // List of files with module and package documentation
57 // http://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation
58 includes = ['packages.md', 'extra.md']
59
60 // The list of files or directories containing sample code (referenced with @sample tags)
61 samples = ['samples/basic.kt', 'samples/advanced.kt']
62
63 jdkVersion = 6 // Used for linking to JDK
64
65 // Use default or set to custom path to cache directory
66 // to enable package-list caching
67 // When set to default, caches stored in $USER_HOME/.cache/dokka
68 cacheRoot = 'default'
69
70 // Use to include or exclude non public members.
71 includeNonPublic = false
72
73 // Do not output deprecated members. Applies globally, can be overridden by packageOptions
74 skipDeprecated = false
75
76 // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions
77 reportUndocumented = true
78
79 skipEmptyPackages = true // Do not create index pages for empty packages
80
81 impliedPlatforms = ["JVM"] // See platforms section of documentation
82
83 // Manual adding files to classpath
84 // This property not overrides classpath collected from kotlinTasks but appends to it
85 classpath = [new File("$buildDir/other.jar")]
86
87 // By default, sourceRoots is taken from kotlinTasks, following roots will be appended to it
88 // Short form sourceRoots
89 sourceDirs = files('src/main/kotlin')
90
91 // By default, sourceRoots is taken from kotlinTasks, following roots will be appended to it
92 // Full form sourceRoot declaration
93 // Repeat for multiple sourceRoots
94 sourceRoot {
95 // Path to source root
96 path = "src"
97 // See platforms section of documentation
98 platforms = ["JVM"]
99 }
100
101 // Specifies the location of the project source code on the Web.
102 // If provided, Dokka generates "source" links for each declaration.
103 // Repeat for multiple mappings
104 linkMapping {
105 // Source directory
106 dir = "src/main/kotlin"
107
108 // URL showing where the source code can be accessed through the web browser
109 url = "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin"
110
111 // Suffix which is used to append the line number to the URL. Use #L for GitHub
112 suffix = "#L"
113 }
114
115 // No default documentation link to kotlin-stdlib
116 noStdlibLink = false
117
118 // Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka)
119 // Repeat for multiple links
120 externalDocumentationLink {
121 // Root URL of the generated documentation to link with. The trailing slash is required!
122 url = new URL("https://example.com/docs/")
123
124 // If package-list file located in non-standard location
125 // packageListUrl = new URL("file:///home/user/localdocs/package-list")
126 }
127
128 // Allows to customize documentation generation options on a per-package basis
129 // Repeat for multiple packageOptions
130 packageOptions {
131 prefix = "kotlin" // will match kotlin and all sub-packages of it
132 // All options are optional, default values are below:
133 skipDeprecated = false
134 reportUndocumented = true // Emit warnings about not documented members
135 includeNonPublic = false
136 }
137 // Suppress a package
138 packageOptions {
139 prefix = "kotlin.internal" // will match kotlin.internal and all sub-packages of it
140 suppress = true
141 }
142}
143```
144
145To generate the documentation, use the `dokka` Gradle task:
146
147```bash
148./gradlew dokka
149```
150
151More dokka tasks can be added to a project like this:
152
153```groovy
154task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) {
155 outputFormat = 'javadoc'
156 outputDirectory = "$buildDir/javadoc"
157}
158```
159
160Please see the [Dokka Gradle example project](https://github.com/JetBrains/kotlin-examples/tree/master/gradle/dokka-gradle-example) for an example.
161
162#### Android
163
164If you are using Android there is a separate Gradle plugin. Just make sure you apply the plugin after
165`com.android.library` and `kotlin-android`.
166
167```groovy
168buildscript {
169 repositories {
170 jcenter()
171 }
172
173 dependencies {
174 classpath "org.jetbrains.dokka:dokka-android-gradle-plugin:${dokka_version}"
175 }
176}
177
178apply plugin: 'com.android.library'
179apply plugin: 'kotlin-android'
180apply plugin: 'org.jetbrains.dokka-android'
181```
182
183### Using the Maven plugin
184
185The Maven plugin is available in JCenter. You need to add the JCenter repository to the list of plugin repositories if it's not there:
186
187```xml
188<pluginRepositories>
189 <pluginRepository>
190 <id>jcenter</id>
191 <name>JCenter</name>
192 <url>https://jcenter.bintray.com/</url>
193 </pluginRepository>
194</pluginRepositories>
195```
196
197Minimal Maven configuration is
198
199```xml
200<plugin>
201 <groupId>org.jetbrains.dokka</groupId>
202 <artifactId>dokka-maven-plugin</artifactId>
203 <version>${dokka.version}</version>
204 <executions>
205 <execution>
206 <phase>pre-site</phase>
207 <goals>
208 <goal>dokka</goal>
209 </goals>
210 </execution>
211 </executions>
212</plugin>
213```
214
215By default files will be generated in `target/dokka`.
216
217The following goals are provided by the plugin:
218
219 * `dokka:dokka` - generate HTML documentation in Dokka format (showing declarations in Kotlin syntax);
220 * `dokka:javadoc` - generate HTML documentation in JavaDoc format (showing declarations in Java syntax);
221 * `dokka:javadocJar` - generate a .jar file with JavaDoc format documentation.
222
223The available configuration options are shown below:
224
225```xml
226<plugin>
227 <groupId>org.jetbrains.dokka</groupId>
228 <artifactId>dokka-maven-plugin</artifactId>
229 <version>${dokka.version}</version>
230 <executions>
231 <execution>
232 <phase>pre-site</phase>
233 <goals>
234 <goal>dokka</goal>
235 </goals>
236 </execution>
237 </executions>
238 <configuration>
239
240 <!-- Set to true to skip dokka task, default: false -->
241 <skip>false</skip>
242
243 <!-- Default: ${project.artifactId} -->
244 <moduleName>data</moduleName>
245 <!-- See list of possible formats below -->
246 <outputFormat>html</outputFormat>
247 <!-- Default: ${project.basedir}/target/dokka -->
248 <outputDir>some/out/dir</outputDir>
249
250 <!-- Use default or set to custom path to cache directory to enable package-list caching. -->
251 <!-- When set to default, caches stored in $USER_HOME/.cache/dokka -->
252 <cacheRoot>default</cacheRoot>
253
254 <!-- List of '.md' files with package and module docs -->
255 <!-- http://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation -->
256 <includes>
257 <file>packages.md</file>
258 <file>extra.md</file>
259 </includes>
260
261 <!-- List of sample roots -->
262 <samplesDirs>
263 <dir>src/test/samples</dir>
264 </samplesDirs>
265
266 <!-- Used for linking to JDK, default: 6 -->
267 <jdkVersion>6</jdkVersion>
268
269 <!-- Do not output deprecated members, applies globally, can be overridden by packageOptions -->
270 <skipDeprecated>false</skipDeprecated>
271 <!-- Emit warnings about not documented members, applies globally, also can be overridden by packageOptions -->
272 <reportNotDocumented>true</reportNotDocumented>
273 <!-- Do not create index pages for empty packages -->
274 <skipEmptyPackages>true</skipEmptyPackages>
275
276 <!-- See platforms section of documentation -->
277 <impliedPlatforms>
278 <platform>JVM</platform>
279 </impliedPlatforms>
280
281 <!-- Short form list of sourceRoots, by default, set to ${project.compileSourceRoots} -->
282 <sourceDirectories>
283 <dir>src/main/kotlin</dir>
284 </sourceDirectories>
285
286 <!-- Full form list of sourceRoots -->
287 <sourceRoots>
288 <root>
289 <path>src/main/kotlin</path>
290 <!-- See platforms section of documentation -->
291 <platforms>JVM</platforms>
292 </root>
293 </sourceRoots>
294
295 <!-- Specifies the location of the project source code on the Web. If provided, Dokka generates "source" links
296 for each declaration. -->
297 <sourceLinks>
298 <link>
299 <!-- Source directory -->
300 <dir>${project.basedir}/src/main/kotlin</dir>
301 <!-- URL showing where the source code can be accessed through the web browser -->
302 <url>http://github.com/me/myrepo</url>
303 <!--Suffix which is used to append the line number to the URL. Use #L for GitHub -->
304 <urlSuffix>#L</urlSuffix>
305 </link>
306 </sourceLinks>
307
308 <!-- No default documentation link to kotlin-stdlib -->
309 <noStdlibLink>false</noStdlibLink>
310
311 <!-- Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka) -->
312 <externalDocumentationLinks>
313 <link>
314 <!-- Root URL of the generated documentation to link with. The trailing slash is required! -->
315 <url>https://example.com/docs/</url>
316 <!-- If package-list file located in non-standard location -->
317 <!-- <packageListUrl>file:///home/user/localdocs/package-list</packageListUrl> -->
318 </link>
319 </externalDocumentationLinks>
320
321 <!-- Allows to customize documentation generation options on a per-package basis -->
322 <perPackageOptions>
323 <packageOptions>
324 <!-- Will match kotlin and all sub-packages of it -->
325 <prefix>kotlin</prefix>
326
327 <!-- All options are optional, default values are below: -->
328 <skipDeprecated>false</skipDeprecated>
329 <!-- Emit warnings about not documented members -->
330 <reportUndocumented>true</reportUndocumented>
331 <includeNonPublic>false</includeNonPublic>
332 </packageOptions>
333 </perPackageOptions>
334 </configuration>
335</plugin>
336```
337
338Please see the [Dokka Maven example project](https://github.com/JetBrains/kotlin-examples/tree/master/maven/dokka-maven-example) for an example.
339
340[Output formats](#output_formats)
341
342### Using the Ant task
343
344The Ant task definition is also contained in the dokka-fatjar.jar referenced above. Here's an example of using it:
345
346```xml
347<project name="Dokka" default="document">
348 <typedef resource="dokka-antlib.xml" classpath="dokka-fatjar.jar"/>
349
350 <target name="document">
351 <dokka src="src" outputdir="doc" modulename="myproject"/>
352 </target>
353</project>
354```
355
356The Ant task supports the following attributes:
357
358 * `outputDir` - the output directory where the documentation is generated
359 * `outputFormat` - the output format (see the list of supported formats above)
360 * `classpath` - list of directories or .jar files to include in the classpath (used for resolving references)
361 * `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)
362 * `moduleName` - the name of the module being documented (used as the root directory of the generated documentation)
363 * `include` - names of files containing the documentation for the module and individual packages
364 * `skipDeprecated` - if set, deprecated elements are not included in the generated documentation
365 * `jdkVersion` - version for linking to JDK
366 * `impliedPlatforms` - See [platforms](#platforms) section
367 * `<sourceRoot path="src" platforms="JVM" />` - analogue of src, but allows to specify [platforms](#platforms)
368 * `<packageOptions prefix="kotlin" includeNonPublic="false" reportUndocumented="true" skipDeprecated="false"/>` -
369 Per package options for package `kotlin` and sub-packages of it
370 * `noStdlibLink` - No default documentation link to kotlin-stdlib
371 * `<externalDocumentationLink url="https://example.com/docs/" packageListUrl="file:///home/user/localdocs/package-list"/>` -
372 linking to external documentation, packageListUrl should be used if package-list located not in standard location
373 * `cacheRoot` - Use `default` or set to custom path to cache directory to enable package-list caching. When set to `default`, caches stored in $USER_HOME/.cache/dokka
374
375
376### Using the Command Line
377
378To run Dokka from the command line, download the [Dokka jar](https://github.com/Kotlin/dokka/releases/download/0.9.10/dokka-fatjar.jar).
379To generate documentation, run the following command:
380
381 java -jar dokka-fatjar.jar <source directories> <arguments>
382
383Dokka supports the following command line arguments:
384
385 * `-output` - the output directory where the documentation is generated
386 * `-format` - the [output format](#output-formats):
387 * `-classpath` - list of directories or .jar files to include in the classpath (used for resolving references)
388 * `-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)
389 * `-module` - the name of the module being documented (used as the root directory of the generated documentation)
390 * `-include` - names of files containing the documentation for the module and individual packages
391 * `-nodeprecated` - if set, deprecated elements are not included in the generated documentation
392 * `-impliedPlatforms` - List of implied platforms (comma-separated)
393 * `-packageOptions` - List of package options in format `prefix,-deprecated,-privateApi,+warnUndocumented;...`
394 * `-links` - External documentation links in format `url^packageListUrl^^url2...`
395 * `-noStdlibLink` - Disable documentation link to stdlib
396 * `-cacheRoot` - Use `default` or set to custom path to cache directory to enable package-list caching. When set to `default`, caches stored in $USER_HOME/.cache/dokka
397
398
399### Output formats<a name="output_formats"></a>
400
401 * `html` - minimalistic html format used by default
402 * `javadoc` - Dokka mimic to javadoc
403 * `html-as-java` - as `html` but using java syntax
404 * `markdown` - Markdown structured as `html`
405 * `gfm` - GitHub flavored markdown
406 * `jekyll` - Jekyll compatible markdown
407 * `kotlin-website*` - internal format used for documentation on [kotlinlang.org](https://kotlinlang.org)
408
409### Platforms<a name="platforms"></a>
410
411Dokka can annotate elements with special `platform` block with platform requirements
412
413Example of usage can be found on [kotlinlang.org](https://kotlinlang.org/api/latest/jvm/stdlib/)
414
415Each source root has a list of platforms for which members are suitable.
416Also, the list of 'implied' platforms is passed to Dokka.
417If a member is not available for all platforms in the implied platforms set, its documentation will show
418the list of platforms for which it's available.
419
420## Dokka Internals
421
422### Documentation Model
423
424Dokka uses Kotlin-as-a-service technology to build `code model`, then processes it into `documentation model`.
425`Documentation model` is graph of items describing code elements such as classes, packages, functions, etc.
426
427Each node has semantic attached, e.g. Value:name -> Type:String means that some value `name` is of type `String`.
428
429Each reference between nodes also has semantic attached, and there are three of them:
430
4311. Member - reference means that target is member of the source, form tree.
4322. Detail - reference means that target describes source in more details, form tree.
4333. Link - any link to any other node, free form.
434
435Member & Detail has reverse Owner reference, while Link's back reference is also Link.
436
437Nodes that are Details of other nodes cannot have Members.
438
439### Rendering Docs
440
441When we have documentation model, we can render docs in various formats, languages and layouts. We have some core services:
442
443* FormatService -- represents output format
444* LocationService -- represents folder and file layout
445* SignatureGenerator -- represents target language by generating class/function/package signatures from model
446
447Basically, given the `documentation` as a model, we do this:
448
449```kotlin
450 val signatureGenerator = KotlinSignatureGenerator()
451 val locationService = FoldersLocationService(arguments.outputDir)
452 val markdown = JekyllFormatService(locationService, signatureGenerator)
453 val generator = FileGenerator(signatureGenerator, locationService, markdown)
454 generator.generate(documentation)
455```
456
457## Building Dokka
458
459Dokka is built with Gradle. To build it, use `./gradlew build`.
460Alternatively, open the project directory in IntelliJ IDEA and use the IDE to build and run Dokka.
461
462Here's how to import and configure Dokka in IntelliJ IDEA:
463
464* Select "Open" from the IDEA welcome screen, or File > Open if a project is
465 already open
466* Select the directory with your clone of Dokka
467 * Note: IDEA may have an error after the project is initally opened; it is OK
468 to ignore this as the next step will address this error
469* After IDEA opens the project, select File > New > Module from existing sources
470 and select the `build.gradle` file from the root directory of your Dokka clone
471* Use the default options and select "OK"
472* After Dokka is loaded into IDEA, open the Gradle tool window (View > Tool
473 Windows > Gradle) and click on the top left "Refresh all Gradle projects"
474 button
475* Verify the following project settings. In File > Settings > Build, Execution,
476 Deployment > Build Tools > Gradle > Runner:
477 * Ensure "Delegate IDE build/run actions to gradle" is checked
478 * "Gradle Test Runner" should be selected in the "Run tests using" drop-down
479 menu
480* Note: After closing and re-opening the project, IDEA may give an error
481 message: "Error Loading Project: Cannot load 3 modules". Open up the details
482 of the error, and click "Remove Selected", as these module `.iml` files are
483 safe to remove.
484