Improve the Kotlin documentation

1

I’ve just looked at FileTreeWalk and find it not overly helpful.

  • The page doesn’t show how to actually use the class. There are very view examples in the docs.
  • The page lists private constructor parameters. There is not hint how to obtain an instance.
  • There is no compact overview over all methods (like in JavaDoc, ScalaDoc)
  • Sometimes the return type is the thing to look for, what is very easy in JavaDoc
  • ScalaDoc has a nice filter to reduce the list of classes.
  • There is no overview over all class like in JavaDoc or ScalaDoc.

It would be nice, if the Kotlin documentation could be redesigned in a way, that the above points would be improved.

2

  • I’m not sure what you mean by “There is no compact overview over all methods”. The “Functions” section in the page you have linked to is intended to perform exactly that role. How is it different from what you expect to see?

  • What exactly do you mean by “Sometimes the return type is the thing to look for, what is very easy in JavaDoc”? How exactly would you expect the documentation to be changed to address this suggestion ?

  • The overview of all classes is available here: alltypes - Kotlin Programming Language

The rest are valid points; we’ll address them, but it doesn’t look like this would require a redesign of the entire documentation system.

3

I’m not sure what you mean by “There is no compact overview over
all methods”. The “Functions” section in the page you have linked to is
intended to perform exactly that role. How is it different from what you
expect to see?

I mean an overview with just the method signature and a short (single sentence) description, like in JavaDoc:

Predicate asPredicate()
Creates a predicate which can be used to match a string.

static Pattern compile(String regex)
Compiles the given regular expression into a pattern.

This short description could then be expanded inline or link to a longer description.

What exactly do you mean by “Sometimes the return type is the thing to
look for, what is very easy in JavaDoc”? How exactly would you expect
the documentation to be changed to address this suggestion ?

I found it practical from time to time, that the return type is the first column in JavaDoc. Let’s say I know, that I want a String, but don’t know the method name, I would just scan for String and find the method (like File.readText()).

The overview of all classes is available here: alltypes - Kotlin Programming Language

Ok, exists, but what I meant was a “frame” (not necessarily a HTML frame) with all classes grouped by packages like ScalaDoc has.

I really like ScalaDoc and consider it the best API doc design so far. Maybe this could be a source of inspiration.

but it doesn’t look like this would require a redesign of the entire documentation system.

“redesign” was meant in a layout sense.

I’m happy to hear, that you are further improving the documentation.

4

That’s exactly how the documentation is rendered, isn’t it?

Anyway, I’ve filed an issue to clarify the documentation of FileTreeWalk: https://youtrack.jetbrains.com/issue/KT-13297.

5

That’s exactly how the documentation is rendered, isn’t it?

No, it’s not! See for example the API doc of the Array class.

728×1118 80.2 KB

There is much more than just a sentence. And there is no additional overview like in JavaDoc.