Javadoc complexity

[Stephen Colebourne]

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.

See
http://download.java.net/jdk8/docs/api/java/util/package-summary.html

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

Spliterator.OfPrimitive<T,T_CONS,T_SPLITR extends
Spliterator.OfPrimitive<T,T_CONS,T_SPLITR>>

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:

Spliterator.OfPrimitive<T,T_CONS,T_SPLITR>
EnumMap<K>
EnumSet<E>
EventListenerProxy<T>

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
Spliterator.OfPrimitive<T,T_CONS,T_SPLITR>>


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.

Stephen