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

[Alan Bateman]

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