[PATCH FOR REVIEW]: Fix CORBA documentation warnings

[Joseph D. Darcy]

Andrew John Hughes wrote:
> 2010/1/16 Andrew John Hughes <gnu_andrew at member.fsf.org>:
>   
>> 2010/1/16 Joseph D. Darcy <Joe.Darcy at sun.com>:
>>     
>>> Andrew John Hughes wrote:
>>>       
>>>> 2010/1/15 Ken Cavanaugh <Ken.Cavanaugh at sun.com>:
>>>>
>>>>         
>>>>> The fixes look good to me.
>>>>>
>>>>> Thanks,
>>>>>
>>>>> Ken.
>>>>>
>>>>> On Jan 15, 2010, at 1:59 PM, Joseph D. Darcy wrote:
>>>>>
>>>>>
>>>>>           
>>>>>> Andrew John Hughes wrote:
>>>>>>
>>>>>>             
>>>>>>> When building documentation, both OpenJDK6 and OpenJDK7 spit out a
>>>>>>> number of warnings when building documentation:
>>>>>>>
>>>>>>> /mnt/builder/jdk6/impsrc/javax/rmi/PortableRemoteObject.java:171:
>>>>>>> warning - Tag @link: reference not found: Stub#connect
>>>>>>> /mnt/builder/jdk6/impsrc/org/omg/CORBA/SetOverrideType.java:50:
>>>>>>> warning - Tag @link: reference not found: omg.org.CORBA.Object._se\
>>>>>>> t_policy_override
>>>>>>> /mnt/builder/jdk6/impsrc/org/omg/CORBA/TCKind.java:552: warning - Tag
>>>>>>> @return cannot be used in constructor documentation.  It can\
>>>>>>> only be used in the following types of documentation: method.
>>>>>>> /mnt/builder/jdk6/impsrc/org/omg/CORBA/UnknownUserException.java:62:
>>>>>>> warning - @ is an unknown tag.
>>>>>>> /mnt/builder/jdk6/impsrc/org/omg/CORBA/portable/ServantObject.java:48:
>>>>>>> warning - Tag @return cannot be used in field documentation\
>>>>>>> .  It can only be used in the following types of documentation: method.
>>>>>>>
>>>>>>>
>>>>>>> /mnt/builder/jdk6/impsrc/org/omg/CosNaming/_NamingContextExtStub.java:301:
>>>>>>> warning - @parm is an unknown tag.
>>>>>>> /mnt/builder/jdk6/impsrc/org/omg/CosNaming/_NamingContextStub.java:146:
>>>>>>> warning - @parm is an unknown tag.
>>>>>>>
>>>>>>>
>>>>>>> /mnt/builder/jdk6/impsrc/org/omg/CosNaming/NamingContextOperations.java:89:
>>>>>>> warning - @parm is an unknown tag.
>>>>>>>
>>>>>>>
>>>>>>> /mnt/builder/jdk6/impsrc/org/omg/PortableInterceptor/IORInfoOperations.java:54:
>>>>>>> warning - @param argument "a_component" is not a p\
>>>>>>> arameter name.
>>>>>>>
>>>>>>>
>>>>>>> /mnt/builder/jdk6/impsrc/org/omg/PortableInterceptor/IORInfoOperations.java:72:
>>>>>>> warning - @param argument "a_component" is not a p\
>>>>>>> arameter name.
>>>>>>>
>>>>>>> This patch against OpenJDK7:
>>>>>>>
>>>>>>> http://cr.openjdk.java.net/~andrew/build/webrev.04/corba.patch
>>>>>>>
>>>>>>> fixes the warnings.
>>>>>>>
>>>>>>> Is this ok to push?  If so, can I have a bug ID for it?
>>>>>>>
>>>>>>> Joe, would this also be ok for 6?
>>>>>>>
>>>>>>> Thanks,
>>>>>>>
>>>>>>>
>>>>>>>               
>>>>>> cc'ing Ken Cavanaugh for corba matters.
>>>>>>
>>>>>> If this fix is approved for JDK 7, I approve it to also go back into
>>>>>> OpenJDK 6.
>>>>>>
>>>>>> Regards,
>>>>>>
>>>>>> -Joe
>>>>>>
>>>>>>
>>>>>>             
>>>>>           
>>>> Thanks Ken.  I don't see you on http://db.openjdk.java.net/people so
>>>> not sure what I should use for the Reviewed-by field.
>>>>
>>>> Joe, can you allocate this a bug ID?
>>>>
>>>>         
>>> 6917485 Corba doc warnings
>>>
>>> You can use me as a reviewer for jcheck purposes.
>>>
>>> Have a good weekend,
>>>
>>> -Joe
>>>
>>> PS Monday is a holiday for Sun in the US.
>>>
>>>
>>>       
>> Done:
>>
>> http://hg.openjdk.java.net/jdk6/jdk6/corba/rev/05436b84e93a
>> http://hg.openjdk.java.net/jdk7/build/corba/rev/d4c077d44a64
>>
>> With this fix as well:
>>
>> http://cr.openjdk.java.net/~andrew/build/webrev.05/
>>
>> the main javadoc build passes with no warnings.  There are two
>> remaining warnings from doclets:
>>
>> /mnt/builder/jdk6/impsrc/com/sun/tools/doclets/package.html: warning -
>> Tag @link: reference not found:
>> com.sun.tools.doclets.internal.toolkit.util
>> /mnt/builder/jdk6/impsrc/com/sun/tools/doclets/package.html: warning -
>> Tag @link: reference not found:
>> com.sun.tools.doclets.internal.toolkit.util
>> 2 warnings
>>
>> --
>> Andrew :-)
>>
>> Free Java Software Engineer
>> Red Hat, Inc. (http://www.redhat.com)
>>
>> Support Free Java!
>> Contribute to GNU Classpath and the OpenJDK
>> http://www.gnu.org/software/classpath
>> http://openjdk.java.net
>>
>> PGP Key: 94EFD9D8 (http://subkeys.pgp.net)
>> Fingerprint: F8EF F1EA 401E 2E60 15FA  7927 142C 2591 94EF D9D8
>>
>>     
>
> Does http://cr.openjdk.java.net/~andrew/build/webrev.05/ look ok?
>
> If so, can I have a bug ID to push to 6 and 7?
>
> Thanks,
>   
Ah yes, the specdefault tag.  I forget offhand where these occur in the 
JDK sources, but they have been there for many years and not caused any 
harm so I'm willing having to have specdefault listed in the set of 
known tags to silence some spurious errors.

You can use

6921068 Remove javadoc builds warnings from specdefault tag

for this issue.

I approve this going into OpenJDK 6 and JDK 7.

Thanks,

-Joe