Javadoc complexity

[Brian Goetz]

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
> 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
>