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

[alexander stepanov]

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