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

[K2] Members of enum entry are not displayed #3129

Closed
vmishenev opened this issue Aug 17, 2023 · 0 comments · Fixed by #3180
Closed

[K2] Members of enum entry are not displayed #3129

vmishenev opened this issue Aug 17, 2023 · 0 comments · Fixed by #3180
Assignees
Labels
bug topic: K2 Issues / PRs that are related to the K2 migration. See #2888
Milestone

Comments

@vmishenev
Copy link
Contributor

vmishenev commented Aug 17, 2023

In K2 Dokka does not display members of enum entry, e.g. name and ordinal. if the body of an enum entry is empty (also see KT-61256 )

Dokka K2 will not display anonymous members of entry anymore. It does not make to have documentation for them since they are anonymous and unavailable outside of an enum entry's initializing anonymous object.
Pitfall: Overridden KDoc in an entry (anonymous classes) will not be displayed.

Example

enum class ProtocolState {
    WAITING {
       /*
       * Dokka will display the documentation from the super member on entry page.
       * In this example: `Some KDos`
       */
        override fun signal() = anonymousFun()
        /**
        * This member will be invisible in generated documentation
        */
        fun anonymousFun() =  TALKING
    },

    TALKING {
        override fun signal() = WAITING
    };
    /**
    * Some KDoc
    */
    abstract fun signal(): ProtocolState
}

So the Waiting entry-page will have the members:

  • val name
  • val ordinal
  • fun signal() Note: not override fun signal()
    Some KDoc

Motivation/Technical details
Dokka will get the required members from the enum class's scope since, e.g. the A enum entry in the enum E is

static val A: E = object : E() {
   val x: Int = 5
}

but it needs to exclude all static members like values and valueOf.
x cannot be visible outside the object's initializer and is an implementation detail

@vmishenev vmishenev added the bug label Aug 17, 2023
@vmishenev vmishenev changed the title Empty scope for enum entry in symbols [K2] Members of entry are not displayed Aug 29, 2023
@vmishenev vmishenev changed the title [K2] Members of entry are not displayed [K2] Members of enum entry are not displayed Aug 29, 2023
@vmishenev vmishenev added this to the K2 compiler analysis milestone Aug 30, 2023
@vmishenev vmishenev linked a pull request Sep 18, 2023 that will close this issue
@IgnatBeresnev IgnatBeresnev added the topic: K2 Issues / PRs that are related to the K2 migration. See #2888 label Oct 13, 2023
@IgnatBeresnev IgnatBeresnev modified the milestones: K2 compiler analysis, Dokka 1.9.20 Oct 13, 2023
svc-squareup-copybara pushed a commit to cashapp/misk that referenced this issue Dec 17, 2024
| Package | Type | Package file | Manager | Update | Change |
|---|---|---|---|---|---|
|
[org.jetbrains.dokka:dokka-gradle-plugin](https://github.com/Kotlin/dokka)
| dependencies | misk/gradle/libs.versions.toml | gradle | major |
`1.9.20` -> `2.0.0` |

---

### Release Notes

<details>
<summary>Kotlin/dokka
(org.jetbrains.dokka:dokka-gradle-plugin)</summary>

### [`v2.0.0`](https://github.com/Kotlin/dokka/releases/tag/v2.0.0):
2.0.0

Dokka 2.0.0 focuses on simplifying configuration and preparing for
support of future Kotlin language features. Key highlights include:

- **Dokka Gradle Plugin v2**: revamped Gradle plugin based on
[Dokkatoo](https://github.com/adamko-dev/dokkatoo).
-   **Experimental K2 Analysis**: support for K2 compiler frontend.
- **HTML Improvements**: better accessibility and easier customization.

More details about each of the changes below. See [Dokka
2.0.0](https://github.com/Kotlin/dokka/milestone/31?closed=1) milestone
for the list of all changes.

#### Dokka's Gradle plugin v2 based on
[Dokkatoo](https://github.com/adamko-dev/dokkatoo)

> Please check the [migration
guide](https://kotl.in/dokka-gradle-migration) for the update procedure
and give feedback!

Dokka 2.0.0 introduces significant improvements to Dokka Gradle plugin,
aligning more closely with Gradle best practices:

-   Adopts Gradle types, which leads to better performance.
- Uses an intuitive top-level DSL configuration instead of a low-level
task-based setup, which simplifies the build scripts and their
readability.
- Takes a more declarative approach to documentation aggregation, which
makes multi-project documentation easier to manage.
- Uses a type-safe plugin configuration, which improves the reliability
and maintainability of your build scripts.
- Fully supports Gradle [configuration
cache](https://docs.gradle.org/current/userguide/configuration_cache.html)
and [build
cache](https://docs.gradle.org/current/userguide/build_cache.html),
which improves performance and simplifies build work.

##### Changes from Dokka 2.0.0-Beta

- Forward Dokka Generator messages to Gradle logger
(Kotlin/dokka#3833)
- Add deprecated property to help migrate from JSON Dokka plugin
configuration (Kotlin/dokka#3877)
- Rename `dokkaPublicationDirectory` to `basePublicationsDirectory`
(Kotlin/dokka#3876)
- Rename `dokkaModuleDirectory`, and mark as internal
(Kotlin/dokka#3880)
- Update and add KDoc for DGPv2
(Kotlin/dokka#3842)
- Remove DokkaPluginParametersBuilder
(Kotlin/dokka#3872)
- Increase default max heap of Worker to 2G
(Kotlin/dokka#3913)
- Remove the dependency of `dokkaGenerate` on `dokkaGenerateModule*`
(Kotlin/dokka#3920)
- KT-71784 Fix classpath for KMP shared source sets
(Kotlin/dokka#3942)
- Fix DGP/KMP integration, so Dokka can 'see' code from shared source
sets in target source sets (Kotlin/dokka#3814)

#### Dokka's K2 analysis

Dokka 2.0.0 introduces **K2 analysis**, which is currently in an
experimental stage. Dokka's K2 analysis leverages Kotlin's K2 compiler
frontend for analysing code and uses the same shared Analysis API, which
is used in [IntelliJ IDEA’s K2
mode](https://blog.jetbrains.com/idea/2024/11/k2-mode-becomes-stable/).
The output with K2 analysis should mostly match that of K1 analysis, but
there may be minor differences. We are actively working towards
stabilizing K2 analysis and are planning to enable K2 analysis by
default in future.

To opt in to Dokka's K2 analysis, add the following flag to your
project's `gradle.properties` file:

```properties
org.jetbrains.dokka.experimental.tryK2=true
```

##### Known limitations:

- Intersecting source roots
([#&#8203;3701](Kotlin/dokka#3701)) and
intersecting sample roots
([#&#8203;3373](Kotlin/dokka#3373)) may cause
issues.
- Kotlin/JS libraries compiled with the [legacy Kotlin/JS
compiler](https://kotlinlang.org/docs/js-ir-compiler.html) are not
supported ([#&#8203;3751](Kotlin/dokka#3751)).

We would greatly value your feedback if you encounter any of these
limitations.

##### Potential differences between the outputs of K1 and K2:

While the output of K2 analysis aims to align with K1, there are some
differences to be aware of:

- Java synthetic properties: rendering may vary
([details](Kotlin/dokka#2888 (comment))).
- KDoc links: resolution and rendering differences
([details](Kotlin/dokka#2888 (comment))).
- Inconsistent documentable rendering order
([#&#8203;3590](Kotlin/dokka#3590)).
- Enum entries: anonymous and overridden methods are no longer rendered
([#&#8203;3129](Kotlin/dokka#3129)).
- Other differences may arise due to variations in type inference
between K1 and K2.

#### HTML format

Dokka 2.0.0 introduces some changes to HTML output. We updated the
structure of some elements and classes, particularly in the navigation
and sidebar, to improve accessibility and simplify maintenance. These
changes only affect you if you previously
[customized](https://kotlinlang.org/docs/dokka-html.html#customization)
Dokka styles.

- We removed redundant wrappers like `navigation--inner` and
`navigation-title`.
- We reworked blocks such as `versions-dropdown` to make them more
accessible.
- We renamed classes like `navigation-controls--homepage` to improve
consistency. For example, it’s now called
`navigation-controls--btn_homepage`.

For more information, see the [pull
request](https://github.com/Kotlin/dokka/pull/3917/files).

The easiest way to update your current templates is to adjust the [new
templates](https://github.com/Kotlin/dokka/tree/master/dokka-subprojects/plugin-base/src/main/resources/dokka/templates)
to your needs.

#### Bugfixes

- Fix merging expect-actual declarations
(Kotlin/dokka#3875)

#### Other changes

- Update the external link URL for stdlib
(Kotlin/dokka#3938)

#### Feedback

We would appreciate your feedback!

-   Please report any feedback or problems https://kotl.in/dokka-issues
- Chat with the community visit #dokka in https://kotlinlang.slack.com/
(To sign up visit https://kotl.in/slack)

**Full Changelog**:
Kotlin/dokka@v1.9.20...v2.0.0

</details>

---

### Configuration

📅 **Schedule**: Branch creation - "after 6pm every weekday,before 2am
every weekday" in timezone Australia/Melbourne, Automerge - At any time
(no schedule defined).

🚦 **Automerge**: Disabled by config. Please merge this manually once you
are satisfied.

♻ **Rebasing**: Whenever PR becomes conflicted, or you tick the
rebase/retry checkbox.

🔕 **Ignore**: Close this PR and you won't be reminded about this update
again.

---

- [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check
this box

---

This PR has been generated by [Renovate
Bot](https://github.com/renovatebot/renovate).

GitOrigin-RevId: 585ec9cbb39b481920aae89e0c6884b1e682110a
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug topic: K2 Issues / PRs that are related to the K2 migration. See #2888
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants