Javadoc complexity

Stephen Colebourne scolebourne at
Tue Aug 27 03:57:42 PDT 2013

The Javadoc of JDK8 is starting to show some unecessary complexity
folowing the library changes for lambda. This needs combatting to
avoid scaring developers. This is therefore a request for a minor
tweak to Javadoc.


Note in particular that there is some immediate "in your face" type
parameter complexity:

Spliterator.OfPrimitive<T,T_CONS,T_SPLITR extends

Other examples are less bad (and pre-existing):
EnumMap<K extends Enum<K>,V>>
EnumSet<E extends Enum<E>>
EventListenerProxy<T extends EventListener>

I am proposing that Javadoc is changed so that any extends/super
clause in the type parameters is omitted from the package summary
page. Thus, the examples would become:


I believe that this shorter form is entirely appropriate for the
high-level package summary view, and a lot moe readable.

I also believe that the title of the type-specific page could have the
same simplification, with the full signiture in smaller font beneath:

large font:
Interface Spliterator.OfPrimitive<T,T_CONS,T_SPLITR>
smaller font:
Full signature: Spliterator.OfPrimitive<T,T_CONS,T_SPLITR extends

Java generics are verbose and tricky to understand. We can't afford to
put users off as the level of generics in signatures gets even more
complex with lambdas.


More information about the lambda-dev mailing list