Dokka: Suggestion: Group Methods or Classes

[norswap]

Would it be possible to create groups of methods and/or classes in a package, for the purpose of documentation?

Rationale: the documentation pages can get quite long, and there is often a logical grouping to be made. At the same time, one does not necessarily want to split the methods between packages and require extra imports.

Being able to require that top-level methods and classes be grouped per file for certain files (maybe specify this as a file-scope annotation?) would be a great start.

[yole]

If there is a logical grouping of entities in your code, why deprive those who work with your code from access to that grouping, and present it only in the documentation?

I don't see how, with IntelliJ's import management features, requiring extra imports is a problem at all. You don't need to write them, and you don't need to see them.

[norswap]

If there is a logical grouping of entities in your code, why deprive those who work with your code from access to that grouping, and present it only in the documentation?

They wouldn't be deprived of it, if the methods are grouped inside the same file, or appear sequentially in the code separated by some form of heading comment (e.g., // ----- My Section ------).

I don't see how, with IntelliJ's import management features, requiring extra imports is a problem at all. You don't need to write them, and you don't need to see them.

There is a cognitive dissonance here with the fact that everything in the standard library is imported by default (unlike in Java).

Furthermore, if you consider a library that works with 3 or 4 "kinds" of objects, of which there are many variants. I would group those into categories, and you suggest to fit these categories into packages. So now each time I use my library, I must import things from these 4 packages. It's hardly insurmountable, but if I'm going to do it every time, that looks like a blatant DRY violation.

---

For an example of why this would be beneficial, consider https://kotlinlang.org/api/latest/jvm/stdlib/kotlin.collections/-list/. I don't consider the laundry list of methods at the bottom to be especially user friendly. It would pay to split it a few sections: one for accessing elements of the list, one for filtering or taking subsets of the list, one for conversions, one for sorting, ...

[superbobry]

Here's a good example of how useful grouping can be for libraries with large number of functions. It isn't from the Java world, but it illustrates the point nonetheless.

[yole]

They wouldn't be deprived of it if they looked at the source code of your library. However, they wouldn't see any of this structure if they used regular IDE features such as code completion to explore its API.

The main reason why most of the standard library is imported by default (actually not everything - e.g. kotlin.comparators isn't imported by default) is that the split of the standard library into packages happened very late in the development of Kotlin 1.0, and we wanted to minimize the impact on existing applications.

I agree that the list of extension functions for List is kind of hard to read, but given that those extension functions are declared in many different places, a file-based grouping wouldn't help much. A better solution would be a tag such as @group that could be applied to the doc comments of different functions, regardless of where they are declared.