@Builder methods do not copy javadoc in last @param comment and @Singular and Sub Class

[JaesungAhn]

related #2481

1. last @param case
   do not generate last @param field comment

public class Test {
    private String firstField;
    private String secondField;
    private String lastField;

    /**
     * @param firstField Comment First
     * @param secondField Comment Second
     * @param lastField Comment Last
    */
    @Builder
    public Test(final String firstField, final String secondField, final String lastField) {
        this.firstField= firstField;
        this.secondField= secondField;
        this.lastField= lastField;
    }

    private void bla() {
        Test.builder()
            .firstField("a") // <--- no Javadoc displayed in tooltip without delombok, but delombok would generate Javadoc
            .secondField("b") // <--- no Javadoc displayed in tooltip without delombok, but delombok would generate Javadoc
            .lastField("c") // <--- no Javadoc displayed in tooltip without delombok, and delombok won't generate Javadoc
            .build();
    }
}

public class Test {
    private String firstField;
    private String secondField;
    private String lastField;

    /**
     * @param firstField Comment First
     * @param secondField Comment Second
     * @param lastField Comment Last
     * @author user <--- Add any comments at the end. generate javadoc last @param field
    */
    @Builder
    public Test(final String firstField, final String secondField, final String lastField) {
        this.firstField= firstField;
        this.secondField= secondField;
        this.lastField= lastField;
    }

    private void bla() {
        Test.builder()
            .firstField("a") // <--- no Javadoc displayed in tooltip without delombok, but delombok would generate Javadoc
            .secondField("b") // <--- no Javadoc displayed in tooltip without delombok, but delombok would generate Javadoc
            .lastField("c") // <--- no Javadoc displayed in tooltip without delombok, but delombok would generate Javadoc
            .build();
    }
}

2. @Singular case
   do not generate @Singular field and singular name of this field comment

public class Test {
    private String firstField;
    private List<String> secondField;
    private List<String> lastField;

    /**
     * @param firstField Comment First
     * @param secondField Comment Second
     * @param lastField Comment Last
     * @author user
    */
    @Builder
    public Test(final String firstField, final List<String> secondField, @Singular("addLast") final List<String> lastField) {
        this.firstField= firstField;
        this.secondField= secondField;
        this.lastField= lastField;
    }

    private void bla() {
        Test.builder()
            .firstField("a") // <--- no Javadoc displayed in tooltip without delombok, but delombok would generate Javadoc
            .secondField(null) // <--- no Javadoc displayed in tooltip without delombok, but delombok would generate Javadoc
            .lastField(null) // <--- no Javadoc displayed in tooltip without delombok, and delombok won't generate Javadoc
            .addLast("c") // <--- no Javadoc displayed in tooltip without delombok, and delombok won't generate Javadoc
            .build();
    }
}

3. Sub Class case
   do not generate all field comment

public class Test {
    ...~~...

    public static class Sub {
        /** 
         * @param firstField Comment First
         * @param secondField Comment Second
         * @param lastField Comment Last
        */
        @Builder
        public Sub(final String firstField, final String secondField, final String lastField) {
            this.firstField= firstField;
            this.secondField= secondField;
            this.lastField= lastField;
        }
    }
    private void bla() {
        Test.Sub.builder()
            .firstField("a") // <--- no Javadoc displayed in tooltip without delombok, and delombok won't generate Javadoc
            .secondField("b") // <--- no Javadoc displayed in tooltip without delombok, and delombok won't generate Javadoc
            .lastField("c") // <--- no Javadoc displayed in tooltip without delombok, and delombok won't generate Javadoc
            .build();
    }
}

[Rawi01]

Can confirm 1 and 2 but was unable to reproduce 3.

[Rawi01]

The singular methods are a bit more complex because we generate multiple methods for the same field/parameter and only have one source comment. I think there are three possible solutions:

1. Add some special syntax to support multiple comments (most likely hard to understand)
2. Copy the same comment to both builder methods (might be confusing if the comment is about a collection)
3. Ignore the singular case and copy the comment only to the regular builder method (no comment at all)

WDYT?

[JaesungAhn]

oh.. it's complex...
how about add parameter to @Singular annotation like 'description' or 'javadocComment'?

for example :
@Singular(value="addSome", description="add some to list") final List someList

I think that the solution can be applied to both the constructor parameter and the class field.

[Rawi01]

This should work but it somehow feels wrong to add the javadoc to an annotation. This also means that there are two different locations for comments and that you have to use multiple concatenated strings for longer multiline comments.

[JaesungAhn]

I agree with you
How about applying the second solution as a base and applying the first solution additionally?
Thanks for your hard work :)