25

Where shall I put Javadoc analogy for attributes in KDoc in Kotlin data class?

In other words, how to write in Kotlin KDoc the following Java code Javadoc:

/**
 * Represents a person.
 */
public class Person {
    /**
     * First name. -- where to place this documentation in Kotlin?
     */
    private final String firstName;
    /**
     * Last name. -- where to place this documentation in Kotlin?
     */
    private final String lastName;

    // a lot of boilerplate Java code - getters, equals, hashCode, ...
}

In Kotlin it looks like this:

/**
 * Represents a person.
 */
data class Person(val firstName: String, val lastName: String)

but where to put the attributes' documentation?

Honza Zidek
  • 9,204
  • 4
  • 72
  • 118

1 Answers1

33

As described in the documentation, you can use the @property tag for this:

/**
 * Represents a person.
 * @property firstName The first name.
 * @property lastName The last name.
 */
data class Person(val firstName: String, val lastName: String)

Alternatively, simply mention the property names in the description of the class, if you don't have much to say about them in the docs:

/**
 * Represents a person, with the given [firstName] and [lastName].
 */
data class Person(val firstName: String, val lastName: String)
yole
  • 92,896
  • 20
  • 260
  • 197
  • 4
    It's a pity that IntelliJ Idea does *not* generate the skeleton when I type `/**` in front of the class - in a similar way as it *does* for method parameters. It is a lost chance to educate us :) – Honza Zidek Apr 05 '18 at 14:39
  • 3
    It's intentional. See http://kotlinlang.org/docs/reference/coding-conventions.html#documentation-comments for an explanation why. – yole Apr 05 '18 at 14:39
  • That's a valid point. Please consider enhancing your answer with this information, this *is* educational. I mean that it is intentional and why - you have already touched this reason anyway. – Honza Zidek Apr 05 '18 at 14:41