Thanks! ----- Исходное сообщение ----- От: roger.ri...@oracle.com Кому: alexander.v.stepa...@oracle.com Копия: core-libs-dev@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 >>> >> >
