Javadoc complexity

Brian Goetz brian.goetz at
Tue Aug 27 08:43:32 PDT 2013

We are likely going to be (finally) revisiting many things Javadoc in 9. 
  There are indeed many information-presentation choices like this that 
could be revisited -- I'll put this on the list.

On 8/27/2013 6:57 AM, Stephen Colebourne wrote:
> 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
> 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

More information about the lambda-dev mailing list