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
|
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:
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)
```
Samples
====
[Dokka docs](http://orangy.github.io/dokka/doc/dokka/index.html) 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
```bash
ant fatjar
```
Build dokka and maven plugin
```bash
ant install-fj
cd maven-plugin
mvn install
```
Build dokka and install maven plugin (do not require maven installed)
```bash
ant build-and-install
```
### Using Maven plugin
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>
```
### Using Gradle plugin
```groovy
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:
```groovy
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
```bash
./gradlew dokka
```
|
