Use consistent javadoc style for annotation links

[dreis2211]

Hi,

while doing a PR the other day, I found that Spring-Boot has several styles for annotations in javadocs. E.g. I found the following:

• {@link ExampleAnnotation}
• {@link ExampleAnnotation @ExampleAnnotation}
• @{@link ExampleAnnotation}

The last one is something that should probably be fixed, because it creates a link on the annotation-name, that doesn't include the @ sign.

From the official docs I would say, that annotations are not treated specially, so I'm not sure what to do with the second option.

If you decide on a style, I'd be happy to contribute the necessary changes. Either the minimal one (just fixing occurences of case 3) or the big one (aligning everything).

Let me know what you think.

Cheers,
Christoph

[snicoll]

Thanks for spotting this Christoph. I am in favour of harmonizing this indeed and I've flagged for team attention to see what the rest of the team thinks. We should hopefully get back soon with a plan.

[philwebb]

FWIW I prefer {@link ExampleAnnotation @ExampleAnnotation}

[dreis2211]

For completeness reasons: Option 2 is probably the most effort.

[philwebb]

We generally prefer option 2, but lets just try to do that going forward. Searching for all links that happen to be annotations sounds very time consuming.

[dreis2211]

I can't get my head about that sentence, sorry 😄 Should I prepare a PR for option 2 or not?

[wilkinsona]

If you have the time to do it, a PR for option 2 would be most welcome. We just don't want you to feel in any way obliged as we've picked the most time consuming option!

[dreis2211]

No worries. I don't feel any time pressure on this and will provide one when I have time. I've raised the effort concern only to help with the decision process, not to make my life easier.

[wilkinsona]

In need of something a bit different to work on, I've updated my Eclipse plugin to find and warn about javadoc links to annotations that don't match our preferred style. There appears to be over 400 of them… I should probably implement a quick fix rather than someone tackling this manually.