Hi! Kotlin documentation <says> it's better to omit `@param` and `@return` statements from document...

# announcements

[jvmusin]

Hi!

Kotlin documentation says it's better to omit @param and @return statements from documentation wherever it's possible and mention them explicitly in the description. Do you agree with it and do you really try to omit them or you still use a javadoc-like documentation?

[asad.awadia]

I don't use param and returns. Feels too much like php

[jvmusin]

@asad.awadia people usually seem to hate php (for no reason mostly), do you hate your docs?)

[asad.awadia]

For no reason? Lol

[asad.awadia]

Hate my docs?

[jvmusin]

I mean people who never tried php hate it, so yep, no reasons there
I haven't tried it too btw

[asad.awadia]

One don't need to put their hand in the fire to know it's a bad idea

[jvmusin]

sure lol

[jvmusin]

I just don't feel very comfortable with IDEA's behaviour. When you use Java, IDEA generates some templates for javadocs, but it doesn't do any of these things for Kotlin's KDoc.

[CLOVIS]

Why ask if we agree, if you already decided you don't?

[asad.awadia]

That's whatever? Just write them yourself? That is such a barrel scrape-ing nit

[asad.awadia]

Nobody will praise good docs because they were generated by idea and vice versa

[nanodeath]

so what I do is describe at a high level what the method returns in the description, and then get as specific as reasonably possible in @return, like

/**
 * Returns a list of all the foos that bar.
 * @return a new read-only list of [Foo].
 */

at least, so long as it's not obvious from the method signature. like implementation details (e.g. ordering) that you want as a part of the method contract.

[adk]

I suspect that the main point of avoiding @return is to avoid unnecessary boilerplate when possible - consistent with kotlin ethos. The docs are clear that you should use @return et. al when the description doesn't really fit the flow of the main text. The kotlinesque version of your example would be:

/**
 * Returns a new read-only list of all the [Foo]s
 * that bar.
 */

I'm sure different people have a personal preference for one or the other, but if you are collaborating with other developers, it is best to a) be consistent and b) avoid bike-shedding.

[nanodeath]

given I'm used to ~0 documentation, I'll settle for anything provided it's correct and not overly verbose or specific 🙂

[jvmusin]

@adk I agree that your example is easier to read and follow. I've been looking at Kotlin sources docs for some time and it feels good to me. Sometimes they use @return, but only when the function does something and not just retrieving/mapping elements. In those situations they write Returns x if something or y otherwise without any @return or @param . Thank you)

[turansky]

I just don’t feel very comfortable with IDEA’s behaviour.

It main reason why I use @param and @return . IDEA has more readable/organized popup in this case.

[turansky]

One more argument - @param allows to see information for specific parameter. It’s very useful when method/constructor have many parameters.

[jvmusin]

@turansky It makes sense, I write docs the same way rn. There is a plugin KDoc-er for IDEA which helps writing docs in this style. I was using it before I read about these KDoc style recommendations.

[louiscad]

For properties defined in the constructor, you might want to use @property so it's shown in the doc of that property.

[turansky]

One more related opened question - @see alternatives

[turansky]

With @param

[turansky]

Without @param

[turansky]

Looks like mode “without `@param`” isn’t tested in IDEA 😞

[jvmusin]

@turansky I think this is intended behavior. In the first example you document a parameter whereas in the second one you just write a doc for the constructor itself. Did you expect something else?

[jvmusin]

Okay, I see what happened in the second case. This is probably because they expect to see @constructor at the end with all other @-starting things. At least, KDoc-er generates @constructor at the end