```/** * Displays text. * @param text the text ...

# codereview

[Ellen Spertus]

/**
 * Displays text.
 * @param text the text
 * @param size the font size
 * @param isBold whether the font should be bold
 * @param isItalic whether the font should be italic
 * @param isUnderlined whether the text should be underlined
 */
fun displayText(
    text: String, size: Int,
    isBold: Boolean, isItalic: Boolean, isUnderlined: Boolean
)

Please give me feedback on the KDoc. (This is for an example of the benefits of default argument values.)

[Daniel Pitts]

Which is bold and/or italic, the font or the text? Genuine question, since terminology around text rendering can be tricky 😉

[Daniel Pitts]

Other than that, I prefer boolean parameter descriptions to be in the form if true, the x will do y .

[Daniel Pitts]

Also, though this advice is outside of the scope of your example, boolean arguments are often a code-smell. In this example specifically, I might use enums instead. enum Weight { Normal, Bold } enum Slant { Roman, Italicized } enum Decoration { None, Underlined }

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

I would avoid kdoc that just repeats the name of the parameter. Self-explanatory code is the best documentation, and this is just noise.

[christophsturm]

what @Zach Klippenstein (he/him) [MOD] said. all the current info in the kdoc is obsolete imo. maybe instead write how the text is displayed or where. anything that is not obvious.

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

Good stuff for param kdoc is stuff like how params interact with each other (especially if subtle or surprising), value requirements (eg for a Float “should be between 0 and 1” or something), info on less trivial params where the name+type aren’t enough to inform the reader what they might need to pass, etc

[CLOVIS]

Hey! Please take a look at the official code style:

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.

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

In particular, as other posters have mentioned, repeating the name of the field provides little value.

Also, your documentation doesn't really answer the most interesting questions. In your example, it's not clear what the size argument's unit is. It could be in points, it could be in pixels. It could be in any other unit. This is what we expect documentation to expose.

But, we can go one step further using `value class`:

fun displayText(
    …,
    size: TextSize,
    …,
)

and you can have multiple constructors to allow callers to use whichever unit they find more convenient:

displayText(
    …,
    size = 2.pt,
    …,
)

Using this approach along enums (as already recommended), there is almost no need to document anything anymore, as only explicit code can compile.