RFR 8161965 -> Fwd: JDK 9 RFR of 8161402: Provide a javadoc description for java.prefs module

[Lance Andersen]

Hi all,

Take 2 on the  module description javadocs.

http://cr.openjdk.java.net/~lancea/8161965 <http://cr.openjdk.java.net/~lancea/8161965>

the xxx.01 include the updated changes.

Alan, I tried to incorporate your suggested changes.  Hopefully we are getting closer.

Best
Lance
> On Jul 21, 2016, at 1:41 PM, Lance Andersen <lance.andersen at oracle.com> wrote:
> 
> 
>> On Jul 21, 2016, at 1:03 PM, Alan Bateman <Alan.Bateman at oracle.com> wrote:
>> 
>> On 21/07/2016 17:37, Lance Andersen wrote:
>> 
>>> I took a stab at the javadoc descriptions for the modules modeled after what we discussed for the java.prefs module.
>>> 
>>> The webrev can be found at http://cr.openjdk.java.net/~lancea/8161965/ <http://cr.openjdk.java.net/~lancea/8161965/>
>> It's good to do these in bulk and get some consistently.
>> 
>> A general comment is that it uses acronyms for several APIs. For example java.xml say "JAXP" then I assume it should have "XML Processing". JDBC, JNDI, JAXB, ... there are several that I think should be clearer.
> 
> I can add the JCP naming for the ones that are applicable,  for JDBC that is correct it is not an acronym 
>> 
>> java.activation has "activation API", shouldn't this be "JavaBeans Activation Framework”.
> Yes
>> 
>> I'm not sure what to say for java.annotations.common. I think it has to say something about it defining a subset of the Common Annotations.
> I can add that before the …. core JAX-WS wording
>> 
>> For java.transaction then the exceptions also for interop with CORBA Transaction Services. The text might need to say that it's the Java SE subset of the Java Transaction API.
>> 
> OK will take another stab at this, I was leveraging wording from the javadocs
>> The java.management module exports java.lang.management so that will need text.
> OK must have missed that
> 
> 
> Once I hear from others, I will push another webrev
> 
>> 
>> I think Jon Gibbons is working on text for java.compiler and jdk.compiler so you might be able to drop java.compiler from your patch.
>> 
> OK, or Jon can just suggest his preferred wording… either way is fine.
> 
> Best
> Lance
>> -Alan
>> 
>> 
>> 
>> 
> 
> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
> <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
> <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
> Oracle Java Engineering 
> 1 Network Drive 
> Burlington, MA 01803
> Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>
> 
> 
> 

 <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif> <http://oracle.com/us/design/oracle-email-sig-198324.gif>
 <http://oracle.com/us/design/oracle-email-sig-198324.gif>Lance Andersen| Principal Member of Technical Staff | +1.781.442.2037
Oracle Java Engineering 
1 Network Drive 
Burlington, MA 01803
Lance.Andersen at oracle.com <mailto:Lance.Andersen at oracle.com>