Update and add KDoc for DGPv2 #3842
Conversation
adam-enko
added
the
runner: Gradle plugin
| abstract val moduleVersion: Property<String> | ||
|
|
||
| /** | ||
| * A distinct relative path for the Dokka Module produced by the current project. |
There was a problem hiding this comment.
not sure I understand what this property could be used for when reading KDoc :(
| @@ -83,32 +104,9 @@ constructor( | |||
| ) | |||
|
|
|||
| /** | |||
| * Dokka Source Sets describe the source code that should be included in a Dokka Publication. | |||
| * Dokka Source Sets describe the source code that should be included in the generated output. | |||
There was a problem hiding this comment.
Dokka Source Set not only represents the source code, but also its Dokka configuration. I would say, for end-users configuration part is more important in DSL
| @@ -153,6 +148,9 @@ constructor( | |||
| * } | |||
| * ``` | |||
| * | |||
| * _Aside: Launching [without isolation][WorkerExecutor.noIsolation] is not an option, because | |||
There was a problem hiding this comment.
not sure it's needed here, as it's not actionable (e.g why I need to know this, why it's required, what is it, etc)
probably we can safely remove this part
| * | ||
| * _Aside: Launching [without isolation][WorkerExecutor.noIsolation] is not an option, because | ||
| * running Dokka Generator **requires** an isolated classpath._ | ||
| * - a new process, using [ProcessIsolation], |
There was a problem hiding this comment.
minor: probably it's better to write here WHY someone needs to change this. E.g as in example, regarding memory usage.
| * ``` | ||
| * | ||
| * @see url |
There was a problem hiding this comment.
not sure why @see is needed here, isn't it will redirect to itself?
| * | ||
| * Note: You can cache files locally and provide them to Dokka as local paths. | ||
| * See [DokkaSourceSetSpec.externalDocumentationLinks]. | ||
| */ |
There was a problem hiding this comment.
would be nice to add default values in docs for all properties
| * | ||
| * This is an internal Dokka Gradle plugin property. | ||
| * If you find you need to set this property, please report your use-case https://kotl.in/dokka-issues. | ||
| */ |
There was a problem hiding this comment.
let's add @DokkaInternalApi?
| @@ -23,7 +23,7 @@ import kotlin.annotation.AnnotationTarget.* | |||
| * [the Dokka issue tracker](https://github.com/Kotlin/dokka/issues). | |||
| */ | |||
| @RequiresOptIn( | |||
| message = "Internal Dokka API - may change at any time without notice", | |||
| message = "Internal Dokka Gradle API - may change at any time without notice", | |||
There was a problem hiding this comment.
BTW, may be it makes sense to rename it to @InternalDokkaGradlePluginApi?
- to emphasise that it's related to Gradle Plugin
- to use naming convention which is used in most libraries I saw:
- @ Severity Domain Api?
- SEVERITY = e.g experimental or internal
- DOMAIN = based on library name
- @ Severity Domain Api?
| // return Result.failure(ex) | ||
| // } | ||
| // } | ||
| // When the minimum supported Java version is 11+ |
KT-71890