commit | 64c8f35c00fcf483da76451b276e750533fbe9a4 | [log] [tgz] |
---|---|---|
author | Simon Ogorodnik <Simon.Ogorodnik@jetbrains.com> | Fri Feb 10 16:34:26 2017 +0300 |
committer | Simon Ogorodnik <Simon.Ogorodnik@jetbrains.com> | Fri Feb 10 16:34:26 2017 +0300 |
tree | b67771eff37bd1569f0c9a067b309143b52ad3a3 | |
parent | 4517ce588431fc6080bad24d947c53c8d82fcaa0 [diff] |
Tweaking of sample formatting
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 in Kotlin files, and can generate documentation in multiple formats including standard Javadoc, HTML and Markdown.
To run Dokka from the command line, download the Dokka 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
- Markdowngfm
- GitHub-Flavored Markdownjekyll
- Markdown adapted for Jekyll sitesjavadoc
- 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 documentationThe Ant task definition is also contained in the dokka-fatjar.jar referenced above. Here's an example of using it:
<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 generatedoutputformat
- 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 packagesskipdeprecated
- if set, deprecated elements are not included in the generated documentationThe Maven plugin is available in JCenter. You need to add the JCenter repository to the list of plugin repositories if it's not there:
<pluginRepositories> <pluginRepository> <id>jcenter</id> <name>JCenter</name> <url>https://jcenter.bintray.com/</url> </pluginRepository> </pluginRepositories>
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
.
The following goals are provided by the plugin:
dokka:dokka
- generate HTML documentation in Dokka format (showing declarations in Kotlin syntax);dokka:javadoc
- generate HTML documentation in JavaDoc format (showing declarations in Java syntax);dokka:javadocJar
- generate a .jar file with JavaDoc format documentation.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>
Please see the Dokka Maven example project for an example.
buildscript { repositories { 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:
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" } sourceDirs = files('src/main/kotlin') }
To get it generated use gradle dokka
task
./gradlew dokka
More dokka tasks can be added to a project like this:
task dokkaJavadoc(type: org.jetbrains.dokka.gradle.DokkaTask) { outputFormat = 'javadoc' outputDirectory = "$buildDir/javadoc" }
Please see the Dokka Gradle example project for an example.
If you are using Android there is a separate gradle plugin. Just make sure you apply the plugin after com.android.library
and kotlin-android
.
buildscript { repositories { jcenter() } dependencies { classpath "org.jetbrains.dokka:dokka-android-gradle-plugin:${dokka_version}" } } apply plugin: 'com.android.library' apply plugin: 'kotlin-android' apply plugin: 'org.jetbrains.dokka-android'
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 & Detail has reverse Owner reference, while Link's back reference is also Link.
Nodes that are Details of other nodes cannot have Members.
When we have documentation model, we can render docs in various formats, languages and layouts. We have some core services:
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)
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.