aboutsummaryrefslogtreecommitdiff
path: root/runners/maven-plugin/src/main/kotlin/ExternalDocumentationLinkBuilder.kt
blob: 5eb4f26995966fcfe86150b71bc1fab753d606fa (plain)
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
/*
 * Copyright 2014-2023 JetBrains s.r.o. Use of this source code is governed by the Apache 2.0 license.
 */

package org.jetbrains.dokka.maven

import org.apache.maven.plugins.annotations.Parameter
import org.jetbrains.dokka.ExternalDocumentationLink
import org.jetbrains.dokka.ExternalDocumentationLinkImpl
import java.net.URL

/**
 * Configuration block that allows creating links leading to externally hosted
 * documentation of your dependencies.
 *
 * For instance, if you are using types from `kotlinx.serialization`, by default
 * they will be unclickable in your documentation, as if unresolved. However,
 * since API reference for `kotlinx.serialization` is also built by Dokka and is
 * [published on kotlinlang.org](https://kotlinlang.org/api/kotlinx.serialization/),
 * you can configure external documentation links for it, allowing Dokka to generate
 * documentation links for used types, making them clickable and appear resolved.
 *
 * Example:
 *
 * ```xml
 * <externalDocumentationLinks>
 *     <link>
 *         <url>https://kotlinlang.org/api/latest/jvm/stdlib/</url>
 *         <packageListUrl>file:/${project.basedir}/stdlib.package.list</packageListUrl>
 *     </link>
 * </externalDocumentationLinks>
 * ```
 */
public class ExternalDocumentationLinkBuilder {

    /**
     * Root URL of documentation to link with. **Must** contain a trailing slash.
     *
     * Dokka will do its best to automatically find `package-list` for the given URL, and link
     * declarations together.
     *
     * It automatic resolution fails or if you want to use locally cached files instead,
     * consider providing [packageListUrl].
     *
     * Example:
     *
     * ```xml
     * <url>https://kotlinlang.org/api/latest/jvm/stdlib/</url>
     * ```
     */
    @Parameter(name = "url", required = true)
    public var url: URL? = null

    /**
     * Specifies the exact location of a `package-list` instead of relying on Dokka
     * automatically resolving it. Can also be a locally cached file to avoid network calls.
     *
     * Example:
     *
     * ```xml
     * <packageListUrl>file:/${project.basedir}/stdlib.package.list</packageListUrl>
     * ```
     */
    @Parameter(name = "packageListUrl", required = true)
    public var packageListUrl: URL? = null

    public fun build(): ExternalDocumentationLinkImpl = ExternalDocumentationLink(url, packageListUrl)
}