RFR [9] 8079075: some docs cleanup for CORBA - part 1

[Alexander Stepanov]

Thanks!

----- Исходное сообщение -----
От: Roger.Riggs at Oracle.com
Кому: alexander.v.stepanov at oracle.com
Копия: core-libs-dev at openjdk.java.net
Отправленные: Четверг, 30 Апрель 2015 г 21:41:05 GMT +03:00 Москва, Санкт-Петербург, Волгоград
Тема: Re: RFR [9] 8079075: some docs cleanup for CORBA - part 1

Hi Alexander,

The improvements look good to me.

Thank you,  Roger


On 4/30/2015 12:35 PM, alexander stepanov wrote:
> Hello Roger,
>
> Thank you for the notes; please see the updated webrev:
> http://cr.openjdk.java.net/~avstepan/8079075/webrev.01/
>
> Regards,
> Alexander
>
> On 30.04.2015 16:47, Roger Riggs wrote:
>> Hi Alexander,
>>
>> Thanks for working through all these changes.
>>
>> 0) Is there an upstream version of any of this code?  Making even 
>> cosmetic changes
>>    would make future versions harder to merge.
>>
>> 1) For files that we don't typically generate javadoc for, it is 
>> simpler to avoid adding unnecessary markup.
>> For example:
>>
>> old/src/java.corba/share/classes/com/sun/corba/se/impl/corba/AnyImpl.java:222+ 
>>
>> +     * @return  the {@code TypeCode} for the element in the Any
>>
>> There is not much value in the addition of {@code }.
>>
>> For these kind of files, the javadoc should be well formed and any 
>> warnings/errors should be fixed.
>>
>> 2) a number of changes do not maintain the indentation, for example,
>> -     * @result          the InputStream to marshal value of Any out of.
>> +     * @return  the {@code InputStream} to marshal value of Any out of.
>>
>> Unless all of the indentation is going to be fixed in a file; it is 
>> better to remain consistent with the per file style.
>>
>> 3) Removing degenerate @author tags is great.  But adding an extra 
>> blank line is not desirable.
>>    For example, 
>> old/src/java.corba/share/classes/com/sun/corba/se/impl/ior/GenericTaggedProfile.java:39
>>
>> -/**
>> - * @author
>> - */
>> +
>>
>> 4) For snippets of code, use {@code} instead of a plain or {@literal 
>> ...}
>> These files don't that pattern extensively and its not important to 
>> fix it everywhere since it is in the impl code.
>> But for example, it would make sense here:
>> old/src/java.corba/share/classes/com/sun/corba/se/impl/ior/ObjectAdapterIdNumber.java:31+ 
>>
>>
>> - * internally as arrays of the form { "OldRootPOA", "<number>" },
>> + * internally as arrays of the form { "OldRootPOA", "{@literal 
>> <number>}" },
>>
>> Might be better as:
>> + * internally as arrays of the form {@code { "OldRootPOA", 
>> "<number>" }},
>>
>> 5) The continuation of @param should be indented.
>>
>> src/java.corba/share/classes/com/sun/corba/se/impl/naming/pcosnaming/NamingContextImpl.java 
>>
>> @@ -1204,14 +1202,13 @@
>>      * This operation creates a URL based "iiopname://" format name
>>      * from the Stringified Name of the object.
>>      * @param addr internet based address of the host machine where
>> -    * Name Service is running <p>
>> -    * @param sn Stringified Name of the object <p>
>> *+    * Name Service is running*
>> +    * @param sn Stringified Name of the object
>>
>>
>> 6) correct the punctuation since the line is being modified.
>> src/java.corba/share/classes/com/sun/corba/se/pept/transport/Acceptor.java 
>>
>>
>> -     * @return <code>true</code. if the <code>Acceptor</code> has been
>> +     * @return <code>true</code>. if the <code>Acceptor</code> has been
>>
>> Would read better as:
>> +     * @return <code>true</code> if the <code>Acceptor</code> has been
>>
>>
>> 7)  I don't recognize the strings of the format dNNNNN but they seem 
>> to be referring
>>     to past bug reports and the authors who fixed them.  I doubt they 
>> have any value in
>>     the code anymore. It would probably be fine to just drop the 
>> extra '<>' symbols.
>>     And around the author initials.  <klr>  -->  klr
>>
>> Regards, Roger
>>
>>
>>
>> On 4/30/2015 7:56 AM, alexander stepanov wrote:
>>> P.S. Sorry, not sure if changes like "<d62023>" -> "{@literal 
>>> <d62023>}" (see, e.g., ValueBoxGen24.java) are what expected; please 
>>> correct me if I'm wrong.
>>>
>>> But something should be done; otherwise "<d62023>" is interpreted as 
>>> an unknown HTML tag causing the errors.
>>>
>>> Thanks,
>>> Alexander
>>>
>>> On 30.04.2015 14:31, alexander stepanov wrote:
>>>> Hello,
>>>>
>>>> Could you please review the following fix
>>>> http://cr.openjdk.java.net/~avstepan/8079075/webrev.00/
>>>> for
>>>> https://bugs.openjdk.java.net/browse/JDK-8079075
>>>>
>>>> Just some HTML markup fix for CORBA.
>>>>
>>>> Thanks,
>>>> Alexander
>>>
>>
>