brian.goetz at oracle.com
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.
> 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