Generated methods don't have Javadoc.

[lombokissues]

Migrated from Google Code (issue 59)

[lombokissues]

👤 xrathx   🕗 Oct 06, 2009 at 04:14 UTC

What steps will reproduce the problem?
1.
2.
3.

What is the expected output? What do you see instead?
Hope to see methods Javadoc generated from Lombok.
Copying documents string on private field to generated methods.
For instance, If there is a field that have a field-documents,

/**

• URL of user's profile picture. It can be http://foo.bar/default/png when a user doesn't set
  his/her picture
  */
  @ Getter @ Setter private URL profilePicture;

Expected result would be..

/**

• URL of user's profile picture. It can be http://foo.bar/default/png when a user doesn't set
  his/her picture
  */
  public void setProfilePicture( URL url ) { ... }

/**

• URL of user's profile picture. It can be http://foo.bar/default/png when a user doesn't set
  his/her picture
  */
  public URL getProfilePicture() { ... }

And I hope to add some attributes to distinguish document between Setter and Getter. but don't
have any ideas so far. It's okay.

What version of the product are you using? On what operating system?
Lombok 0.8.5 on Mac OS X 10.5.8.
But this is not platform specific issue.

Please provide any additional information below.
This issue was mentioned earlier on the discussion forum as following URL.
http://groups.google.com/group/project-lombok/browse_thread/thread/5983c2deec1ba71d

[lombokissues]

👤 reinierz   🕗 Oct 16, 2009 at 10:00 UTC

I guess copying the javadoc is fair. Issue accepted, but don't hold your breath on our priority on it. Let's keep it
simple though - we'll just move the text over, verbatim. You don't need @ return or @ param tags in a javadoc -
it won't screw up the produced javadoc. If for whatever reason that does make stuff look really bad, we can
generate some boilerplate @ return or @ param.

[lombokissues]

👤 Maaartinus   🕗 Apr 07, 2010 at 15:33 UTC

And I hope to add some attributes to distinguish document between Setter and Getter. but
don't have any ideas so far.

I'd propose to make it simple: Let's say the getter is the more important thing, so let it
have the javadoc and let the setter have only a reference to the getter. This way you get it
redundant (and need just one more click if you was unlucky enough to have clicked on the
setter). It wouldn't work in case there's only setter, but did anybody ever used it (and
the solution is obvious).

[lombokissues]

👤 reinierz   🕗 Jun 06, 2011 at 19:38 UTC

Issue #170 has been merged into this issue.

[lombokissues]

👤 reinierz   🕗 Jun 06, 2011 at 19:38 UTC

NB: There's interesting discussion on issue #170.

[lombokissues]

👤 Lord.Quackstar   🕗 Jun 07, 2011 at 19:46 UTC

Any work on this? The expected syntax was given on January 13th, 2010 and it was excepted. That was the last time I've heard about it which was over a year ago. This issue is over a year and a half old.

Is this ever going to be implemented? Lots of people would really benefit from this and I think it would help adoption as there are several examples of people turning away from lombok due to its lack of javadoc.

[lombokissues]

👤 stefatwork   🕗 Jun 07, 2011 at 20:20 UTC

I have been watching this issue regularly since last year. Unfortunately I do not think there is any hope to see it implemented in the near future...

[lombokissues]

👤 Lord.Quackstar   🕗 Jun 21, 2011 at 21:00 UTC

I started thinking about how lombok would implement this. But I don't know if its possible

Does Javac or EJC even make available javadoc comments? It seems that by the time lombok gets ahold of the AST all the comments are stripped out. Note that I'm not a lombok expert at all so correct me if I'm wrong.

Next, how will lombok tell the IDE about the new Javadoc? It seems that the usefulness of generating Javadoc isn't there if your own IDE can't show you it. It would only help other programs that use your module.

The way it looks (assuming that the compiler already strips out comments by the time lombok runs), it seems that some kind of parser would need to be run on the source file by delombok to get the javadoc, and that the output is really only useful to the javadoc program.

[lombokissues]

👤 r.spilker   🕗 Jun 22, 2011 at 11:03 UTC

Actually, I'm pretty sure we do have access to the javadoc, and are
possibly ably to generate it.

[lombokissues]

👤 Sebastien.Gringoire   🕗 Oct 11, 2012 at 10:23 UTC

One more year and unfortunately this issue is still here. Is there any technical reason to delay this issue ?
I think that the javadoc of getter/setter and most for the @ Delegate methods is a very important feature. IMHO, it'll be a major added value to the use of the @ Delegate annotation, especially for large enterprise projects.

[lombokissues]

👤 peter.becker.de   🕗 Jan 21, 2013 at 03:58 UTC

I was just about to point someone at the generated JavaDoc of some lombokified classes, but then I stopped. The JavaDoc on the private members is fine for me (I don't usually leave the source view), but that information gets completely lost in JavaDoc. Which gives us nicely documented getters for the derived data (custom getters), but no documentation at all for the core data (members of @ Data classes). It doesn't even show that they exist, which means most of the API becomes invisible.

We use immutable data structures only, so copying the member documentation onto the getters would be perfectly fine for us (I don't care about the @ return). The constructors would be more tricky, but I'd be actually quite happy with a fixed statement like "Constructor initializing all members.". Even leaving that out is fine for me. This is another thing I don't care much about, it's really more about exposing the member documentation in a way consistent with other getters.

I can see the argument why this shouldn't really matter that much, but I expect that we will be challenged on this. And it might well end with us having to delombokify the code. We would miss it.

[lombokissues]

👤 MichaelPiefel   🕗 Jun 20, 2013 at 12:50 UTC

The issue is now 4 years old. 34 people have starred it, which is the highest number in all open issues. People have stated that they had to stop using Lombok because no Javadoc was generated. Why is it still priority ‘low’?

A project member has stated it should be possible. People have agreed a simple copy of the element’s comment is enough. If not, that could be improved later. I cannot see technical reasons, and none have been raised.

So, please, implement it.

[lombokissues]

👤 reinierz   🕗 Jun 20, 2013 at 22:13 UTC

If you are willing to sponsor our free time to work on a feature we don't personally care about, we'll get right on that. Alternatively, we are going to accept any push request to fix this enchantment request if it fits our coding guidelines, and are willing to help out to make that happen and to provide tech support for anyone that wants to give it a try. Heck, if a pull request does not fit our coding guidelines in the slightest but it has been at least semi-reasonably well tested, we'll run with it and rewrite it.

But, barring any of that, we're going to prefer to work on features that we are going to end up using ourselves.

We are definitely not against this feature and, if we had all the time in the world, we'd definitely write this ourselves. But we don't, so them's the breaks.

[lombokissues]

👤 n.yovchev@synovite.nl   🕗 Jul 08, 2013 at 15:18 UTC

I agree with peter in comment ﹟10 in the sense that the most common use case would be to indeed just copy the documentation from the private member onto the setter and not care about @ return or other fancy stuff.

While that wouldn't be a catch all solution, maybe stuff can be patched with throwing in some additional annotation to turn on/off desired behavior?

NOTE: I know there is not much priority for this issue, but I am commenting anyway as it might provoke some useful discussion about how the feature should be implemented, so it doesn't only handle one use case if it eventually gets implemented.

[lombokissues]

👤 reinierz   🕗 Jul 08, 2013 at 19:30 UTC

Okay, first things first:

Whining that a feature is very popular is not something that will necessarily convince us to take action, so please don't take this as precedent.

Nevertheless:

https://projectlombok.org/download-edge.html

have a go at it.

This version supports javadoc copying from field to getter / setter / wither in delombok, and THAT IS IT - it does nothing in eclipse, and we make no guarantees about what happens in netbeans.

It's smarter than just verbatim copying though: any @ return is stripped from the field and setter/wither and moved to the getter only, and any @ param is stripped from the field and getter and moved to the setter/wither only (it's undefined if you have both wither and setter on the same field, but that'd be weird anyway).

You can go even further and fully define the entire content of the getter/setter/wither using sections, like so:

/**

• Field documentation
• @ see Also.forFieldOnly()
  *
• -- GETTER --
• Getter's documentation
  *
• @ return For getter only
  *
• -- SETTER --
• Setter's documentation
  *
• @ param name For setter only.
• @ return Even this return statement if you really want it (for self-returning setters?)
  *
• -- WITHER --
• Same here
  */
  @ Getter @ Setter @ Wither private int name;

We've had a short look at making this work in eclipse (for example, in the 'javadoc' view), and it's never gonna happen, folks. Many manweeks of work and it's not worth it. Push requests welcome, but, this isn't for the faint of heart.

[lombokissues]

👤 luvarga   🕗 Jul 12, 2013 at 08:49 UTC

Thanks. Is there maven build of cutting edge lombok version somewhere?

[lombokissues]

👤 n.yovchev@synovite.nl   🕗 Jul 12, 2013 at 09:25 UTC

I would also love to test it. Thanks to the wonderful lombok team.

[lombokissues]

👤 reinierz   🕗 Jul 12, 2013 at 15:10 UTC

No maven builds, but we'll release this soon (Probably this monday, with some luck).

[lombokissues]

👤 jphillips.hps   🕗 Sep 16, 2013 at 12:42 UTC

Fantastic work! I just updated some of my classes and it works PERFECTLY. Thank you all so much!

[lombokissues]

👤 n.yovchev@synovite.nl   🕗 Sep 16, 2013 at 14:00 UTC

I have to admit I still haven't tried it. Is it already in official mvn build?

[lombokissues]

👤 maia@lucidfox.org   🕗 Oct 10, 2013 at 12:01 UTC

Doesn't work for me in Eclipse with 0.12.0. When I add Javadoc to the field, the getter still displays no Javadoc in the popup.

[lombokissues]

👤 hendy.shi   🕗 Oct 10, 2013 at 22:51 UTC

Doesn't work for me in Eclipse with 0.12.0. When I add Javadoc to the field, the getter still displays no Javadoc in the popup.

Yup, same with me. Using Lombok 0.12.0, Eclipse Indigo Service Release 2

Btw... Thank you! Lombok is awesome! It makes Java less clunky.

[lombokissues]

👤 flavio.etrusco@logann.com.br   🕗 May 10, 2014 at 21:20 UTC

Does this ticket only apply to generating javadoc from the javadoc tool or per this tickect should the javadoc also be showing "on-the-fly" in Eclipse?

[lombokissues]

👤 reinierz   🕗 May 11, 2014 at 01:19 UTC

I don't know what this ticket applies to, but the 'verified' part of it applies only to the bare minimum of having delombok produce javadocced results, so that if you then feed the delomboked results into the javadoc tool, you get the javadoc on generated methods.

We've looked into adding support for eclipse's popups, but this is done almost entirely outside of the AST model, so it would be a tonne of work, which involves researching all-new places to patch into. We have no plans to do that.

[lombokissues]

👤 n.yovchev@synovite.nl   🕗 May 12, 2014 at 07:38 UTC

Works perfectly fine on Netbeans 7.3, 7.4 and 8, and also on Intellij 13.1.

[lombokissues]

End of migration

[mirabilos]

It is very unfortunate that this was solved in v0.12.0 as it was, leading not only to #2443 but also to problems with IntelliJ as @return is not valid JavaDoc for a slot:

⚠ IntelliJ will remove them on “reindent file”!

I’d have preferred (or would love to have as an option) synthetic @param/@return values, with all the logic in the description, since it pretty much duplicates the description anyway.

[mirabilos]

Cross-linking https://youtrack.jetbrains.com/issue/IDEA-259347 for the IntelliJ issue