delombok: generated Javadoc for getters and setters should be put on @param and @return

[slaout]

Given this code:

/**
 * A super important field, explained here.
 */
@Getter
@Setter
private String foo;

Lombok and delombokify just copy the Javadoc "as is" onto the getter and setter.

But when doing "mvn javadoc:javadoc" on the project, it complains about missing @param on setter and missing @return on getter.

I don't want to ignore such generated classes, because they contain other non-lombok-managed code that need Javadoc to be compiled and verified.

So I propose delombokify to generate such code:

/**
 * @param foo a super important field, explained here
 */
public String setFoo(String foo) { this.foo = foo; }

/**
 * @return a super important field, explained here
 */
public String getFoo() { return foo; }

Bonus point for lowercasing the first character and removing the final "." character for code style compliance ;-)

[jwgmeligmeyling]

It is possible to define @returns and @param on the fields javadoc, lombok will move it:

NEW in lombok v1.12.0: javadoc on the field will now be copied to generated getters and setters. Normally, all text is copied, and @return is moved to the getter, whilst @param lines are moved to the setter. Moved means: Deleted from the field's javadoc. It is also possible to define unique text for each getter/setter. To do that, you create a 'section' named GETTER and/or SETTER. A section is a line in your javadoc containing 2 or more dashes, then the text 'GETTER' or 'SETTER', followed by 2 or more dashes, and nothing else on the line. If you use sections, @return and @param stripping for that section is no longer done (move the @return or @param line into the section).

However, if these tags are absent, I would agree that copying the fields javadoc as default is nicer than an empty javadoc.

[Tillerino]

With the newer JDKs (I think this started with JDK 11, but I'm not sure), javadoc compilation by default lints very strictly. You'll be seeing this a lot: warning: no @return and with the default settings, the Javadoc Maven Plugin will fail when used on delomboked sources that don't manually specify all @param and @return parameters. So it would be great if delombok by default produced code that passes the new linting.

While that's not the case, and you don't want to add "water is wet" twice to every field Javadoc, the commonly suggested fix is to just turn of the linting of the Javadoc altogether. This can be done with <additionalOptions>-Xdoclint:none</additionalOptions> in the Javadoc Maven Plugin.

If you're on Java 8 source, javadoc compilation will still fail with javadoc: error - The code being documented uses modules but the packages defined in https://docs.oracle.com/javase/8/docs/api/ are in the unnamed module. Instead of turning off doclint, you can fix both problems by declaring the correct Java version for the javadoc plugin:

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-javadoc-plugin</artifactId>
    <configuration>
        <source>1.8</source>
    </configuration>
</plugin>

[jakobbraun]

I would also be interested in this feature and could also do a PR for it. However, before I start to work on it, would you be willing to integrate this feature?

Reminder for me: Start with looking at: https://github.com/projectlombok/lombok/pull/2487/files

[crutcher]

I'm also interested in this feature; and would be willing to work on a patch.