Draft JEP: Javadoc Tag enhancements

[Martin Desruisseaux]

Hello Kumar

Thanks very much for the proposed improvement in the javadoc tools, this
is very welcome. I would like to express a few wishes for consideration,
related to the repetitious texts:

An option, similar to -noqualifier, for replacing parameterized type by
the diamond operator in summaries (the full parameter types would still
be present in the description). See for example the interfaces summary
of java.util package in JDK8 [1]: the left column is very large because
of Spliterator.OfPrimitive<T,T_CONS,T_SPLITR extends
Spliterator.OfPrimitive<T,T_CONS,T_SPLITR>>. An abridged form like
Spliterator.OfPrimitive<> would be appreciated. Alternatively, just
omitting the bounds of parameterized types (e.g. "<T,T_CONS,T_SPLITR
...>" where the ellipsis stands for the omitted bounds) would also help
a lot.

Some way to show together (under a single documentation) the getter and
setter methods of a property. In other words, some way to document the
property instead than the getter and setter methods, then show the
signature of getter/setter below the property description in the
generated javadoc.

Some way to show together (under a single documentation) some overloaded
methods. For example the java.util.Arrays class have many overloaded
methods (binarySearch, copyOf, sort, etc.) with almost identical
description except for the primitive type. I would like some way to
instruct the javadoc tool to insert a single description for all
binarySearch methods (for example), followed by their method signatures.

Just my 2 cents...

    Martin


[1] http://download.java.net/jdk8/docs/api/java/util/package-summary.html

Le 04/03/14 22:20, Kumar Srinivasan a écrit :
> Hello,
>
> Here is a preview of the JEP, that will be submitted formally, please
> let us know
> if you have any comments.
>
> Thanks
> Kumar
>