Skip to content

Enum members are listed in backwards order. #2466

@cosinekitty

Description

@cosinekitty

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

  1. Clone the Astronomy Engine repository and change into its directory.
  2. git checkout kotlin
  3. cd source/kotlin
  4. ./gradlew dokkaGfm
  5. 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!

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions