RFR: 8024704: Improve API documentation of ClassLoader and ServiceLoader with respect to enumeration of resources.

[Martijn Verburg]

As a mostly ;-) silent observer on this list I just wanted to say "Thank
You" to everyone for continuing the diligent work to fix issues like this.
I've seen a host of really useful small improvements go in recently (and
docs definitely count as well) - it doesn't go unnoticed!

Cheers,
Martijn


On 8 October 2013 21:06, Alan Bateman <Alan.Bateman at oracle.com> wrote:

> On 08/10/2013 18:19, Daniel Fuchs wrote:
>
>> Hi,
>>
>> Please find below a fix for:
>>
>> 8024704: Improve API documentation of ClassLoader and ServiceLoader
>>          with respect to enumeration of resources.
>> <https://bugs.openjdk.java.**net/browse/JDK-8024704<https://bugs.openjdk.java.net/browse/JDK-8024704>
>> >
>>
>> This is a clarification of the implementation of the
>> ServiceLoader.iterator() method, as well as non normative advice
>> for ClassLoader subclasses overriding getResource() or getResources()
>> to consider overriding the other method in order to keep them
>> consistent with each other.
>>
>> <http://cr.openjdk.java.net/~**dfuchs/webrev_8024704/webrev.**00/<http://cr.openjdk.java.net/~dfuchs/webrev_8024704/webrev.00/>
>> >
>>
> As background to others, the motive for this one stems from a small
> compatibility issue that arose with the JAXP changes to use ServiceLoader
> (it was previous foraging for service configuration files itself). The
> compatibility issue arises with ClassLoader implementations where
> getResource and getResources are inconsistent, and in the JAXP case
> uncovered a server that located an unexpected XML parser.
>
> Daniel - in the @apiNote on getResource it reads "the implementations
> ensure" where it should be "the implementation ensures" or "implementations
> should ensure". Otherwise the wording looks okay to me. Conventions haven't
> been established yet but I would think that @apiNote is a case where you
> can use the full
> line.
>
> -Alan.
>