Are @param @returns in kdocs discouraged? Asking b...

# announcements

[Sourabh Rawat]

Are @param @returns in kdocs discouraged? Asking because I don't see javadoc like doc comments in stdlib or anywhere based on Kotlin.

[Sebastian Aigner]

They are. https://kotlinlang.org/docs/reference/coding-conventions.html#documentation-comments

Generally, avoid using @param and @return tags. Instead, incorporate the description of parameters and return values directly into the documentation comment, and add links to parameters wherever they are mentioned.

[Zach Klippenstein (he/him) [MOD]]

Why is this the recommended practice?

[Ray Ryan]

That's pretty awful advice for val params on constructors

[Zach Klippenstein (he/him) [MOD]]

Agreed, the nice thing about using @param on constructor params is that the documentation automatically gets applied to the properties as well.