Description Andy Lowry 2015-01-14 16:24:05 EST

Currently, eclipse correctly generates fully-qualified names for classes appearing as @link targets in javadoc comments in package-info files. Unfortunately, this makes the javadoc much less readable than it might be if simple class names were used for classes that are in the package being documented.

For readability, I often find myself manually adding the simple class name as a label in these links, but this is error-prone, and even if I get it right, the links will not be correctly updated if a linked class is renamed or moved into or out of the package.

It would be very nice, IMO, if eclipse could manage this automatically for me, e.g. with an option to use simple class name labels for in-package classes when editing package-info.java. As an example of what would be generated in such a case, imagine that I'm editing javadoc for package x.y.z, and I want to link to class x.y.z.Foo. If I type "Foo", eclipse will offer to generate a link for the class, and will insert {@link x.y.z.Foo} if I accept. Under the proposed scheme, the generated link would instead be {@link x.y.z.Foo Foo}.

The same treatment could, of course, apply to member links, not just class links.

With this functionality in place, refactorings such as class/member renames, movement of classes among packages, etc. could cause affected link labels to be added, dropped, or renamed as necessary to maintain correctness. Specifically:

 - when renaming a class or member, existing javadoc links with labels matching the old name should be changed to reflect the new name
 - when moving a class from one package to another, any javadoc links in the old package's package-info should have labels removed, and any links in the new package's package-info should have labels added.

Any existing labels that do not conform to what the automatically generated label would be should remain unchanged in this process, but ideally they should also be flagged with a warning.