From 4943720ffdd0f884a81a25df2782fd037e21744a Mon Sep 17 00:00:00 2001 From: Dmitry Jemerov Date: Fri, 19 May 2017 13:47:25 +0200 Subject: README updated --- README.md | 66 ++++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 44 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index fee57135..a5ea058f 100644 --- a/README.md +++ b/README.md @@ -44,25 +44,32 @@ dokka { moduleName = 'data' outputFormat = 'html' outputDirectory = "$buildDir/javadoc" + + // The list of configurations the dependencies of which + // are included in Dokka's classpath for code analysis processConfigurations = ['compile', 'extra'] + + // List of files with module and package documentation + // http://kotlinlang.org/docs/reference/kotlin-doc.html#module-and-package-documentation includes = ['packages.md', 'extra.md'] + + // The list of files or directories containing sample code (referenced with @sample tags) samples = ['samples/basic.kt', 'samples/advanced.kt'] jdkVersion = 6 // Used for linking to JDK - skipDeprecated = false // Do not output deprecated members, applies globally, can be overridden by packageOptions - reportNotDocumented = true // Emit warnings about not documented members, applies globally, also can be overridden by packageOptions + // Do not output deprecated members. Applies globally, can be overridden by packageOptions + skipDeprecated = false + + // Emit warnings about not documented members. Applies globally, also can be overridden by packageOptions + reportNotDocumented = true skipEmptyPackages = true // Do not create index pages for empty packages impliedPlatforms = ["JVM"] // See platforms section of documentation - // Selector for resolving dokkaFatJar or File for local path to dokka-fatjar - dokkaFatJar = "org.jetbrains.dokka:dokka-fatjar:$dokka_version" - // By default, sourceRoots is taken from processConfigurations // Short form sourceRoots - // If specified, processConfigurations are ignored sourceDirs = files('src/main/kotlin') // By default, sourceRoots is taken from processConfigurations @@ -76,24 +83,34 @@ dokka { platforms = ["JVM"] } - // Mapping to source + // Specifies the location of the project source code on the Web. + // If provided, Dokka generates "source" links for each declaration. // Repeat for multiple mappings linkMapping { + // Source directory dir = "src/main/kotlin" + + // URL showing where the source code can be accessed through the web browser url = "https://github.com/cy6erGn0m/vertx3-lang-kotlin/blob/master/src/main/kotlin" + + // Suffix which is used to append the line number to the URL. Use #L for GitHub suffix = "#L" } // No default documentation link to kotlin-stdlib noStdlibLink = false + // Allows linking to documentation of the project's dependencies (generated with Javadoc or Dokka) // Repeat for multiple links externalDocumentationLink { + // URL of the generated documentation url = new URL("https://example.com/docs") + // If package-list file located in non-standard location // packageListUrl = new URL("file:///home/user/localdocs/package-list") } + // Allows to customize documentation generation options on a per-package basis // Repeat for multiple packageOptions packageOptions { prefix = "kotlin" // will match kotlin and all sub-packages of it @@ -105,7 +122,7 @@ dokka { } ``` -To get it generated use gradle `dokka` task +To generate the documentation, use the `dokka` Gradle task: ```bash ./gradlew dokka @@ -124,7 +141,7 @@ Please see the [Dokka Gradle example project](https://github.com/JetBrains/kotli #### Android -If you are using Android there is a separate gradle plugin. Just make sure you apply the plugin after +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`. ```groovy @@ -157,7 +174,7 @@ The Maven plugin is available in JCenter. You need to add the JCenter repository ``` -Minimal maven configuration is +Minimal Maven configuration is ```xml @@ -210,7 +227,8 @@ The available configuration options are shown below: some/out/dir - + + packages.md extra.md @@ -250,11 +268,15 @@ The available configuration options are shown below: + + ${project.basedir}/src/main/kotlin + http://github.com/me/myrepo - + #L @@ -262,14 +284,17 @@ The available configuration options are shown below: false + + https://example.com/docs + @@ -333,12 +358,7 @@ To generate documentation, run the following command: 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 - * `gfm` - GitHub-Flavored Markdown - * `jekyll` - Markdown adapted for Jekyll sites - * `javadoc` - Javadoc (showing how the project can be accessed from Java) + * `-format` - the [output format](#output-formats): * `-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) @@ -350,6 +370,7 @@ Dokka supports the following command line arguments: * `-noStdlibLink` - Disable documentation link to stdlib ### Output formats + * `html` - minimalistic html format used by default * `javadoc` - Dokka mimic to javadoc * `html-as-java` - as `html` but using java syntax @@ -359,14 +380,15 @@ Dokka supports the following command line arguments: * `kotlin-website*` - internal format used for documentation on [kotlinlang.org](https://kotlinlang.org) ### Platforms + Dokka can annotate elements with special `platform` block with platform requirements Example of usage can be found on [kotlinlang.org](https://kotlinlang.org/api/latest/jvm/stdlib/) -Each source root has list of platforms for which members are suitable. -Also, the list of 'implied' platforms is passed to Dokka, -if member suitable for all platforms from implied platform set, -then only platforms which not contained in the set will be shown. +Each source root has a list of platforms for which members are suitable. +Also, the list of 'implied' platforms is passed to Dokka. +If a member is not available for all platforms in the implied platforms set, its documentation will show +the list of platforms for which it's available. ## Dokka Internals -- cgit