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

[Roger Riggs]

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
>