-
Notifications
You must be signed in to change notification settings - Fork 452
Description
Describe the bug
I have a Kotlin project that includes several enum classes. There is a single source file astronomy.kt
that contains all the code and documentation comments. I am using Dokka to generate "GitHub Flavored Markdown" (gfm). When Dokka encounters an enum declaration like this...
/**
* Selects whether to correct for atmospheric refraction, and if so, how.
*/
enum class Refraction {
/**
* No atmospheric refraction correction (airless).
*/
None,
/**
* Recommended correction for standard atmospheric refraction.
*/
Normal,
/**
* Used only for compatibility testing with JPL Horizons online tool.
*/
JplHor,
}
... it generates markdown with the members listed in reverse order:
//[astronomy](../../../index.md)/[io.github.cosinekitty.astronomy](../index.md)/[Refraction](index.md)
# Refraction
[jvm]\
enum [Refraction](index.md) : [Enum](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-enum/index.html)<[Refraction](index.md)>
Selects whether to correct for atmospheric refraction, and if so, how.
## Entries
| | |
|---|---|
| [JplHor](-jpl-hor/index.md) | [jvm]<br>[JplHor](-jpl-hor/index.md)()<br>Used only for compatibility testing with JPL Horizons online tool. |
| [Normal](-normal/index.md) | [jvm]<br>[Normal](-normal/index.md)()<br>Recommended correction for standard atmospheric refraction. |
| [None](-none/index.md) | [jvm]<br>[None](-none/index.md)()<br>No atmospheric refraction correction (airless). |
## Properties
| Name | Summary |
|---|---|
| [name](../-node-event-kind/-ascending/index.md#-372974862%2FProperties%2F-1216412040) | [jvm]<br>val [name](../-node-event-kind/-ascending/index.md#-372974862%2FProperties%2F-1216412040): [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html) |
| [ordinal](../-node-event-kind/-ascending/index.md#-739389684%2FProperties%2F-1216412040) | [jvm]<br>val [ordinal](../-node-event-kind/-ascending/index.md#-739389684%2FProperties%2F-1216412040): [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html) |
Expected behaviour
The enum members should be documented in the same order they appear in the source code. I chose the above example because it is relatively simple, but there are other cases where the order is more problematic. For example, I have an enumerated type for solar system bodies, and the planets are listed backwards, which is confusing for people using my project. Issue #47 might possibly be related?
Screenshots
N/A
To Reproduce
- Clone the Astronomy Engine repository and change into its directory.
git checkout kotlin
cd source/kotlin
./gradlew dokkaGfm
- Look at the file
source/kotlin/build/dokka/gfm/astronomy/io.github.cosinekitty.astronomy/-refraction/index.md
. It will list the enum values in the order JplHor, Normal, None. The correct order is None, Normal, JplHor.
Dokka configuration
Configuration of dokka used to reproduce the bug:
plugins {
java
kotlin("jvm") version "1.6.10"
`maven-publish`
id("org.jetbrains.dokka") version "1.6.10"
}
group = "io.github.cosinekitty"
version = "0.0.1"
repositories {
mavenCentral()
}
dependencies {
dokkaHtmlPlugin("org.jetbrains.dokka:kotlin-as-java-plugin:1.6.10")
val junit5Version = "5.8.2"
testImplementation("org.junit.jupiter:junit-jupiter-api:$junit5Version")
testImplementation("org.junit.jupiter:junit-jupiter-params:$junit5Version")
testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:$junit5Version")
testImplementation(kotlin("test"))
}
tasks.test {
useJUnitPlatform()
}
configure<JavaPluginExtension> {
sourceCompatibility = JavaVersion.VERSION_1_8
}
val sourceJar by tasks.creating(Jar::class) {
dependsOn(tasks["classes"])
archiveClassifier.set("sources")
from(sourceSets["main"].allSource)
}
task("fatJar", type = Jar::class) {
from(configurations.runtimeClasspath.get().map(::zipTree))
duplicatesStrategy = DuplicatesStrategy.EXCLUDE
with(tasks.jar.get())
}
publishing {
publications {
register("mavenJava", MavenPublication::class) {
from(components["kotlin"])
artifact(sourceJar)
}
}
}
tasks.withType<org.jetbrains.kotlin.gradle.tasks.KotlinCompile>().configureEach {
kotlinOptions {
allWarningsAsErrors = true
}
}
tasks.dokkaGfm.configure {
dokkaSourceSets {
named("main") {
includeNonPublic.set(false)
reportUndocumented.set(true)
}
}
}
Installation
- Operating system: macOS/Windows/Linux: The bug happens in all 3: macOS, Windows 10, and multiple flavors of Debian Linux.
- Build tool: Gradle v7.4.1
- Dokka version: 1.6.10
Additional context
$ ./gradlew --version
------------------------------------------------------------
Gradle 7.4.1
------------------------------------------------------------
Build time: 2022-03-09 15:04:47 UTC
Revision: 36dc52588e09b4b72f2010bc07599e0ee0434e2e
Kotlin: 1.5.31
Groovy: 3.0.9
Ant: Apache Ant(TM) version 1.10.11 compiled on July 10 2021
JVM: 11.0.13 (JetBrains s.r.o. 11.0.13+7-b1751.25)
OS: Linux 4.19.0-20-amd64 amd64
Are you willing to provide a PR?
I am happy to provide whatever help the maintainers could use to reproduce/diagnose this bug. Thank you!