KDoc Property annotation not rendered on page of the property

[AlexW00]

Describe the bug When annotating a property of a class like so:

/**
@property x Property description
*/
class XYZ {
val x = 1
}

It does not appear in the html page of the property XYZ/x, but is only visible on the property page of XYZ/

Expected behaviour The property description should also be visible on the page of XYZ/x

Screenshots Example from my documentation

Class HTML page

Property HTML page

To Reproduce Annotate like so:

/**
@property x Property description
*/
class XYZ {
val x = 1
}

And then generate via dokkaHtml

Dokka configuration Configuration of dokka used to reproduce the bug

apply plugin: 'org.jetbrains.dokka'
dokkaHtml.configure {
    dokkaSourceSets {
        named("main") {
            noAndroidSdkLink.set(false)
            includeNonPublic.set(true)
        }
    }
}
dokkaHtml {
    dokkaSourceSets {
        suppressInheritedMembers.set(true)
        suppressObviousFunctions.set(true)
        moduleName.set("ScreenshotMatcher2")
        configureEach {
            includes.from("screenshotmatcher2.md")
        }
    }
}

tasks.withType(dokkaHtml.getClass()).configureEach {
    pluginsMapConfiguration.set(
            [
             "org.jetbrains.dokka.base.DokkaBase": """{ "customStyleSheets": ["${file("./dokka/logo-styles.css")}"], "customAssets": ["${file("./dokka/dokka_logo.png")}"] }""",
            ]
    )
}

Installation

• Operating system: macOS
• Build tool: Gradle v6.5
• Dokka version: 1.5.30

Additional context none

Are you willing to provide a PR? yes

[IgnatBeresnev]

Reproduced on 1.6.10 with the new html format, thanks for the report

/**
 * @property x Property description
 */
class XYZ {
    val x = 1
}

class page

property page

Also reproduced on

/**
 * @property x Property description
 */
class XYZ(
    val x: Int = 1
)

Which is definitely a valid case as per KDoc spec

[IgnatBeresnev]

Is there any reason you don't want to annotate the property directly? I think this is the preferred way to annotate non-primary-constructor properties and it works just like expected, with documentation being rendered on page of the property

class XYZ {
    /**
     * Property description
     */
    val x = 1
}

Current behavior of dokka is indeed inconsistent and this should be fixed, but I'm not sure which way :)

[AlexW00]

The reason I did annotate that way was because in the official Kdoc guide, only this way of annotating properties was shown: https://kotlinlang.org/docs/kotlin-doc.html

Also, it takes up less space, because you don't have to type "/* /" for each property.

[IgnatBeresnev]

I see, thanks! We need to add more examples to that page.

The primary reason that @property exists is to make it easier to annotate primary constructors (like it was shown):

This tag can be used for documenting properties declared in the primary constructor, where putting a doc comment directly before the property definition would be awkward.

However, when it comes to individual properties (outside of primary constructor), you'll find that they are mostly documented separately, like in Java. Example here, so it's perfectly fine.

[AlexW00]

Oh, okay I see. Unfortunately, I already commented over many files with tons of properties with the "@property" syntax...