When generating documentation for classes with primary constructor without documentation Dokka generates an empty page for primary constructor.
Examples:
In all those cases there exists documentation on a class level, but still, those pages exists and can be opened or searched on web. We can't force web search engines to output the pages we want them to. They would likely prioritize the more verbose ones, but they can also be too smart for their own good and find a constructor's KDoc when asked "how to create a Foo".
In Kotlin, writing constructors in the class signature is the common approach, so it's expected that most primary constructors get no documentation. To document primary constructor, there is a tag @constructor, but in case of "data" classes or abstract classes with empty constructor in most cases the only reasonable comment will look like "this constructor creates object of type X by passing parameter Y and Z" or "this constructor is called when extending X".
Documenting primary constructor in such way is very similar to documenting @return and @param tags with just a description "returns object of type X" (Kotlinlang conventions example).
So having primary constructor undocumented should be fine in most cases and we probably should optimise UX of generated HTML here.
Probably we can rather safely exclude generation of pages for constructors when there is no documentation for them or its parameters leaving constructors block without links to those pages.
Current state is showed below. The only expected change with this proposal is removal of a link from FileMetadata on the left side.
Just dropping the page and inlining documentation on the main page is not an option, as constructor documentation can also be rather big. F.e there is LocalDateTime with three constructors with extensive documentation and samples or ByteString with single constructor which explains how arguments are interpreted.
When generating documentation for classes with primary constructor without documentation Dokka generates an empty page for primary constructor. Examples:
In all those cases there exists documentation on a class level, but still, those pages exists and can be opened or searched on web. We can't force web search engines to output the pages we want them to. They would likely prioritize the more verbose ones, but they can also be too smart for their own good and find a constructor's KDoc when asked "how to create a Foo".
In Kotlin, writing constructors in the class signature is the common approach, so it's expected that most primary constructors get no documentation. To document primary constructor, there is a tag
@constructor, but in case of "data" classes or abstract classes with empty constructor in most cases the only reasonable comment will look like "this constructor creates object of type X by passing parameter Y and Z" or "this constructor is called when extending X". Documenting primary constructor in such way is very similar to documenting@returnand@paramtags with just a description "returns object of type X" (Kotlinlang conventions example).So having primary constructor undocumented should be fine in most cases and we probably should optimise UX of generated HTML here.
Probably we can rather safely exclude generation of pages for constructors when there is no documentation for them or its parameters leaving constructors block without links to those pages. Current state is showed below. The only expected change with this proposal is removal of a link from
FileMetadataon the left side.Just dropping the page and inlining documentation on the main page is not an option, as constructor documentation can also be rather big. F.e there is LocalDateTime with three constructors with extensive documentation and samples or ByteString with single constructor which explains how arguments are interpreted.