Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Enum class properties name and ordinal link to the wrong class. #2464

Open
cosinekitty opened this issue Apr 25, 2022 · 1 comment
Open

Enum class properties name and ordinal link to the wrong class. #2464

cosinekitty opened this issue Apr 25, 2022 · 1 comment
Labels
bug format: gfm An issue/PR related to Dokka's GFM output format

Comments

@cosinekitty
Copy link
Contributor

cosinekitty commented Apr 25, 2022

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...

/**
 * Aberration calculation options.
 *
 * [Aberration](https://en.wikipedia.org/wiki/Aberration_of_light) is an effect
 * causing the apparent direction of an observed body to be shifted due to transverse
 * movement of the Earth with respect to the rays of light coming from that body.
 * This angular correction can be anywhere from 0 to about 20 arcseconds,
 * depending on the position of the observed body relative to the instantaneous
 * velocity vector of the Earth.
 *
 * Some Astronomy Engine functions allow optional correction for aberration by
 * passing in a value of this enumerated type.
 *
 * Aberration correction is useful to improve accuracy of coordinates of
 * apparent locations of bodies seen from the Earth.
 * However, because aberration affects not only the observed body (such as a planet)
 * but the surrounding stars, aberration may be unhelpful (for example)
 * for determining exactly when a planet crosses from one constellation to another.
 */
enum class Aberration {
    /**
     * Request correction for aberration.
     */
    Corrected,

    /**
     * Do not correct for aberration.
     */
    None,
}

... it generates an incorrect and unwanted "Properties" section that contains name and ordinal properties that link to the wrong enum class, as shown in the following example. They are linked to NodeEventKind.Ascending, which does exist in my code, but is a member of an unrelated enum class.

//[astronomy](../../../index.md)/[io.github.cosinekitty.astronomy](../index.md)/[Aberration](index.md)

# Aberration

[jvm]\
enum [Aberration](index.md) : [Enum](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-enum/index.html)<[Aberration](index.md)> 

Aberration calculation options.

[Aberration](https://en.wikipedia.org/wiki/Aberration_of_light) is an effect causing the apparent direction of an observed body to be shifted due to transverse movement of the Earth with respect to the rays of light coming from that body. This angular correction can be anywhere from 0 to about 20 arcseconds, depending on the position of the observed body relative to the instantaneous velocity vector of the Earth.

Some Astronomy Engine functions allow optional correction for aberration by passing in a value of this enumerated type.

Aberration correction is useful to improve accuracy of coordinates of apparent locations of bodies seen from the Earth. However, because aberration affects not only the observed body (such as a planet) but the surrounding stars, aberration may be unhelpful (for example) for determining exactly when a planet crosses from one constellation to another.

## Entries

| | |
|---|---|
| [None](-none/index.md) | [jvm]<br>[None](-none/index.md)()<br>Do not correct for aberration. |
| [Corrected](-corrected/index.md) | [jvm]<br>[Corrected](-corrected/index.md)()<br>Request correction for aberration. |

## 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
Either of the following:

  1. Do not generate the Properties section containing name and ordinal. (My personal preference.) They are not useful because they are a generic part of any enum class; they do not help people trying to understand my code.
  2. If they must be generated, link to the correct class. In this example, the link should be to Aberration, not the unrelated enum class NodeEventKind.

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/-aberration/index.md. It will contain incorrect links to NodeEventKind, as described above.

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!

@cosinekitty cosinekitty changed the title Enum class members name and ordinal link to the wrong class. Enum class properties name and ordinal link to the wrong class. Apr 25, 2022
@IgnatBeresnev IgnatBeresnev added the format: gfm An issue/PR related to Dokka's GFM output format label Apr 25, 2022
@atyrin
Copy link
Contributor

atyrin commented Jul 25, 2023

The issue is present for Dokka 1.9.0 and HTML output.
Reproducer: dokka-kmp-project.zip

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug format: gfm An issue/PR related to Dokka's GFM output format
Projects
None yet
Development

No branches or pull requests

3 participants