#2987 Support for defining Javadoc in the generated mapper implementation by jccampanero · Pull Request #3219 · mapstruct/mapstruct

jccampanero · 2023-03-28T22:07:13Z

The proposed change provides a new annotation allowing the definition of Javadoc comments in the generated Mapper implementation.

For instance, the following definition:

@Javadoc(
    value = "This is the description",
    authors = { "author1", "author2" },
    deprecated = "Use {@link OtherMapper} instead",
    since = "0.1"
)

will generate something like:

/**
* This is the description
* 
* @author author1
* @author author2
* 
* @deprecated Use {@link OtherMapper} instead
* @since 0.1
*/

The annotation allows users to write Text blocks:

@Javadoc(
    """
    This is the description
                   
    @author author1
    @author author2
                   
    @deprecated Use {@link OtherMapper} instead
    @since 0.1
    """
)

or plain old Java Strings:

@Javadoc("This is the description\n"
                   + "\n"
                   + "@author author1\n"
                   + "@author author2\n"
                   + "\n"
                   + "@deprecated Use {@link OtherMapper} instead\n"
                   + "@since 0.1\n")

Fixes #2987.

…entation

filiphr

This looks really good @jccampanero. Thanks a lot for your work on this and sorry that it took me so long to review it.

I've left some comments that I think we should address before we merge this to main.

In addition to the comments. It would perhaps be good to add something in the documentation for this and to also add something in the javadoc of @Mapper, perhaps a @see.

What do you think @jccampanero

jccampanero · 2023-04-22T23:03:52Z

This looks really good @jccampanero. Thanks a lot for your work on this and sorry that it took me so long to review it.

I've left some comments that I think we should address before we merge this to main.

In addition to the comments. It would perhaps be good to add something in the documentation for this and to also add something in the javadoc of @Mapper, perhaps a @see.

What do you think @jccampanero

Thank you very much @filiphr.

There is no need to apologize; on the contrary, I am sorry for the time in providing a pull request.

In addition, thank you very much for your time and for reviewing the code.

I have been working in the changes you proposed: only the tests are still pending, and probably improving the Javadoc comments of the Javadoc annotation.

Of course, I agree with you: I will include a reference to the new functionality in the Javadoc comments of Mapper and in the library documentation. What section of the documentation do you think would be best suited to define the new functionality?

sjaakd · 2023-04-23T08:46:15Z

Nice feature 👍

filiphr

The comments in the Javadoc look good to me.

I've left one small comment for the printing of the error message if something is missing. You could also add an erroneous test for that as well.

For the documentation, I think that we can add an additional section to chapter-3-defining-a-mapper.asciidoc below the "Adding annotations" section, i.e. at the end.

Fix reported error line number, changed after license text inclusion.

Move Rename erroneous javadoc mapper and move it to the JavadocTest

filiphr · 2023-04-30T14:09:45Z

Thanks for the changes @jccampanero. I've pushed one small polishing commit for the tests. Can you please add some docs and then we can merge this?

jccampanero · 2023-04-30T14:27:19Z

Thank you very much for the changes performed in the tests @filiphr.

Of course, I will update the documentation to include the Javadoc functionality.

Can I update JavadocTest to use fixtures as you asked me to do too?

filiphr · 2023-04-30T14:38:00Z

Can I update JavadocTest to use fixtures as you asked me to do too?

I forgot about this. Yes please go ahead and update that test to use fixtures.
I did the polishing thinking that I'll merge it immediately, but then I saw that the documentation was not there yet.

jccampanero · 2023-04-30T14:43:58Z

Thank you very much @filiphr.

Yes, sorry, I have been busy the last week.

filiphr · 2023-04-30T15:03:35Z

Yes, sorry, I have been busy the last week.

No need to apologise @jccampanero. We are all doing this in our free time, as you can see I am also not the most free person as well 😄

filiphr

Only one small typo in the docs

jccampanero · 2023-04-30T16:10:26Z

I implemented the required changes, the one related to the documentation and the other one related to the use of fixtures in the tests.

@filiphr, please, consider review carefully the fixtures provided: I think they are right but I was unable to run the tests in IntelliJ, for any reason the fixtures directory are not being copied to the test output folder in my local setup.

Should we create additional test cases?

jccampanero · 2023-04-30T16:12:02Z

Yes, sorry, I have been busy the last week.

No need to apologise @jccampanero. We are all doing this in our free time, as you can see I am also not the most free person as well 😄

Thank you very much always for your kindness @filiphr, I really appreciate it.

…ciidoc Co-authored-by: Filip Hrisafov <filip.hrisafov@gmail.com>

jccampanero · 2023-04-30T16:23:24Z

@filiphr I would like to perform an additional change before closing the PR if you consider it appropriate.

The generated Javadoc comments always start right straight the new line character, no matter how I configure the FreeMarker template. I mean, it generates:

/**
*

but I think this should be:

/**
 *

Note the space before the asterisk.

Please, can you advice me about how I should modify the FreeMarker template to deal with that situation? Thank you in advance.

jccampanero · 2023-04-30T21:58:14Z

@filiphr I would like to perform an additional change before closing the PR if you consider it appropriate.

The generated Javadoc comments always start right straight the new line character, no matter how I configure the FreeMarker template. I mean, it generates:
/**
*
but I think this should be:
/**
 *
Note the space before the asterisk.

Please, can you advice me about how I should modify the FreeMarker template to deal with that situation? Thank you in advance.

After reviewing the code I think the issue could be motivated by org.mapstruct.ap.internal.writer.IndentationCorrectingWriter and the way it seems to handle whitespace at the beginning of new lines.

If I'm right, I think it's preferable to use the current implementation of the code, as it generates correct Javadoc comments, which is ultimately the only important thing in this case, to avoid changing the current functionality implemented for the rest of the templates.

filiphr · 2023-05-01T06:57:48Z

After reviewing the code I think the issue could be motivated by org.mapstruct.ap.internal.writer.IndentationCorrectingWriter and the way it seems to handle whitespace at the beginning of new lines.

You are right @jccampanero. The IndendationCorrectingWriter is the one which is removing the whitespaces. We'll need to do something special there to properly handle this. I would say that for now it is OK how it looks like. We can create a separate issue for this if you want.

filiphr · 2023-05-01T07:23:20Z

This has been integrated. Thanks @jccampanero

jccampanero · 2023-05-02T21:40:54Z

You are welcome, and thank you for your support @filiphr.

Let's tackle the next issue!!

jccampanero added 2 commits March 28, 2023 23:49

mapstruct#2987 Support for Javadoc in generated Mapper initial implem…

286506a

…entation

Merge branch 'main' into 2987_support_for_javadoc_in_generated_mapper

d420377

filiphr requested changes Apr 22, 2023

View reviewed changes

jccampanero added 7 commits April 22, 2023 20:22

Merge branch 'main' into 2987_support_for_javadoc_in_generated_mapper

8652a31

Change Javadoc annotation retention policy type

de28022

Provide Javadoc documentation for the Javadoc annotation

baad101

Improve Javadoc Freemarker related templates

c3fa867

Make javadoc instance field final in Mapper.

0bf3043

Remove obsolete test reference

1c79639

Check that at least one attribute is provided for @JavaDoc

1571249

filiphr reviewed Apr 23, 2023

View reviewed changes

Comment thread processor/src/main/java/org/mapstruct/ap/internal/processor/MapperCreationProcessor.java Outdated

jccampanero and others added 7 commits April 26, 2023 00:33

Add reference to @JavaDoc annotation in comments.

702eee5

Provide some comments for Javadoc model.

d4d2184

Provide information about AnotationMirror on empty Javadoc annotation.

72b2117

Remove trailing characters on JAVADOC_NO_ELEMENTS error message.

041c974

Add falling test for empty javadoc annotation error.

57fce09

Fix reported error line number

9896924

Fix reported error line number, changed after license text inclusion.

Polishing

ecef346

Move Rename erroneous javadoc mapper and move it to the JavadocTest

jccampanero added 2 commits April 30, 2023 17:30

Minor Javadocs improvements

3e847f6

Add Javadoc annotation documentation.

a8664ed

filiphr reviewed Apr 30, 2023

View reviewed changes

Comment thread documentation/src/main/asciidoc/chapter-3-defining-a-mapper.asciidoc Outdated

Add fixtures to test Javadoc annotation.

4b832c6

Update documentation/src/main/asciidoc/chapter-3-defining-a-mapper.as…

1c13dff

…ciidoc Co-authored-by: Filip Hrisafov <filip.hrisafov@gmail.com>

Small javadoc polishing

e0aa570

filiphr merged commit a8df94c into mapstruct:main May 1, 2023

jccampanero deleted the 2987_support_for_javadoc_in_generated_mapper branch May 2, 2023 21:37

Uh oh!

Uh oh!

Conversation

jccampanero commented Mar 28, 2023 • edited by filiphr Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

filiphr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jccampanero commented Apr 22, 2023

Uh oh!

sjaakd commented Apr 23, 2023

Uh oh!

filiphr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

filiphr commented Apr 30, 2023

Uh oh!

jccampanero commented Apr 30, 2023

Uh oh!

filiphr commented Apr 30, 2023

Uh oh!

jccampanero commented Apr 30, 2023

Uh oh!

filiphr commented Apr 30, 2023

Uh oh!

filiphr left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jccampanero commented Apr 30, 2023

Uh oh!

jccampanero commented Apr 30, 2023

Uh oh!

jccampanero commented Apr 30, 2023

Uh oh!

jccampanero commented Apr 30, 2023

Uh oh!

filiphr commented May 1, 2023

Uh oh!

filiphr commented May 1, 2023

Uh oh!

jccampanero commented May 2, 2023

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

jccampanero commented Mar 28, 2023 •

edited by filiphr

Loading