[PATCH FOR REVIEW]: Fix CORBA documentation warnings

[Andrew John Hughes]

On 28 January 2010 20:07, Joseph D. Darcy <Joe.Darcy at sun.com> wrote:
> 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.
>

It's from jaxws.  That's why I didn't even bother to look at the code
as it's no longer part of the OpenJDK tree.

/mnt/builder/tl/impsrc/javax/jws/WebMethod.java:54: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebParam.java:70: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebParam.java:82: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebParam.java:95: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebParam.java:107: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebResult.java:59: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebResult.java:71: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebResult.java:84: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebService.java:52: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebService.java:68: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebService.java:79: warning -
@specdefault is an unknown tag.
/mnt/builder/tl/impsrc/javax/jws/WebService.java:92: warning -
@specdefault is an unknown tag.

> You can use
>
> 6921068 Remove javadoc builds warnings from specdefault tag
>
> for this issue.
>
> I approve this going into OpenJDK 6 and JDK 7.
>

Done:

http://hg.openjdk.java.net/jdk6/jdk6/jdk/rev/ffceebe8e01f
http://hg.openjdk.java.net/jdk7/build/jdk/rev/b250e6c5a9e5

> Thanks,
>
> -Joe
>
>



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