[prev in list] [next in list] [prev in thread] [next in thread]
List: openjdk-serviceability-dev
Subject: Re: JDK 9 RFR of JDK-8077923: Add missing doclint in javax.management
From: Daniel Fuchs <daniel.fuchs () oracle ! com>
Date: 2015-04-16 7:10:52
Message-ID: 552F607C.5080404 () oracle ! com
[Download RAW message or body]
Hi Joe,
Looks good to me!
+1 for doclint :-)
best regards,
-- daniel
On 4/16/15 4:47 AM, joe darcy wrote:
> Hello,
>
> While trying to turn on doclint checking in the build on more modules,
> it came to my attention that various parts of the javax.management
> package are missing javadoc. Please review the straightforward changes
> to add the missing javadoc:
>
> JDK-8077923: Add missing doclint in javax.management
> http://cr.openjdk.java.net/~darcy/8077923.0/
>
> Patch below.
>
> Once this issue is resolved, I'll do the follow-up work necessary to
> enable doclint checking on the java.management module.
>
> Thanks,
>
> -Joe
>
> ---
> old/src/java.management/share/classes/javax/management/AttributeValueExp.java
> 2015-04-15 19:40:40.296525183 -0700
> +++
> new/src/java.management/share/classes/javax/management/AttributeValueExp.java
> 2015-04-15 19:40:40.116615181 -0700
> @@ -93,11 +93,10 @@
> *
> * @return The <CODE>ValueExp</CODE>.
> *
> - * @exception BadAttributeValueExpException
> - * @exception InvalidApplicationException
> - * @exception BadStringOperationException
> - * @exception BadBinaryOpValueExpException
> - *
> + * @throws BadStringOperationException {@inheritDoc}
> + * @throws BadBinaryOpValueExpException {@inheritDoc}
> + * @throws BadAttributeValueExpException {@inheritDoc}
> + * @throws InvalidApplicationException {@inheritDoc}
> */
> @Override
> public ValueExp apply(ObjectName name) throws
> BadStringOperationException, BadBinaryOpValueExpException,
> ---
> old/src/java.management/share/classes/javax/management/DescriptorKey.java
> 2015-04-15 19:40:40.740303194 -0700
> +++
> new/src/java.management/share/classes/javax/management/DescriptorKey.java
> 2015-04-15 19:40:40.564391190 -0700
> @@ -168,5 +168,9 @@
> @Retention(RetentionPolicy.RUNTIME)
> @Target(ElementType.METHOD)
> public @interface DescriptorKey {
> + /**
> + * Returns the descriptor key.
> + * @return the descriptor key
> + */
> String value();
> }
> ---
> old/src/java.management/share/classes/javax/management/DynamicMBean.java
> 2015-04-15 19:40:41.196075205 -0700
> +++
> new/src/java.management/share/classes/javax/management/DynamicMBean.java
> 2015-04-15 19:40:41.016165202 -0700
> @@ -43,7 +43,7 @@
> *
> * @return The value of the attribute retrieved.
> *
> - * @exception AttributeNotFoundException
> + * @exception AttributeNotFoundException if specified attribute
> does not exist or cannot be retrieved
> * @exception MBeanException Wraps a
> <CODE>java.lang.Exception</CODE> thrown by the MBean's getter.
> * @exception ReflectionException Wraps a
> <CODE>java.lang.Exception</CODE> thrown while trying to invoke the
> getter.
> *
> @@ -58,8 +58,8 @@
> * @param attribute The identification of the attribute to
> * be set and the value it is to be set to.
> *
> - * @exception AttributeNotFoundException
> - * @exception InvalidAttributeValueException
> + * @exception AttributeNotFoundException if specified attribute
> does not exist or cannot be retrieved
> + * @exception InvalidAttributeValueException if value specified
> is not valid for the attribute
> * @exception MBeanException Wraps a
> <CODE>java.lang.Exception</CODE> thrown by the MBean's setter.
> * @exception ReflectionException Wraps a
> <CODE>java.lang.Exception</CODE> thrown while trying to invoke the
> MBean's setter.
> *
> ---
> old/src/java.management/share/classes/javax/management/ImmutableDescriptor.java
> 2015-04-15 19:40:41.639853215 -0700
> +++
> new/src/java.management/share/classes/javax/management/ImmutableDescriptor.java
> 2015-04-15 19:40:41.455945211 -0700
> @@ -65,6 +65,8 @@
> /**
> * Construct a descriptor containing the given fields and values.
> *
> + * @param fieldNames the field names
> + * @param fieldValues the field values
> * @throws IllegalArgumentException if either array is null, or
> * if the arrays have different sizes, or
> * if a field name is null or empty, or if the same field name
> @@ -81,6 +83,7 @@
> * is {@code a=b=c} then the field name is {@code a} and its value
> * is {@code b=c}.
> *
> + * @param fields the field names
> * @throws IllegalArgumentException if the parameter is null, or
> * if a field name is empty, or if the same field name appears
> * more than once, or if one of the strings does not contain
> @@ -94,6 +97,7 @@
> * <p>Construct a descriptor where the names and values of the
> fields
> * are the keys and values of the given Map.</p>
> *
> + * @param fields the field names and values
> * @throws IllegalArgumentException if the parameter is null, or
> * if a field name is null or empty, or if the same field name
> appears
> * more than once (which can happen because field names are not case
> ---
> old/src/java.management/share/classes/javax/management/QueryExp.java
> 2015-04-15 19:40:42.099623225 -0700
> +++
> new/src/java.management/share/classes/javax/management/QueryExp.java
> 2015-04-15 19:40:41.919713221 -0700
> @@ -53,10 +53,13 @@
> *
> * @return True if the query was successfully applied to the
> MBean, false otherwise
> *
> - * @exception BadStringOperationException
> - * @exception BadBinaryOpValueExpException
> - * @exception BadAttributeValueExpException
> - * @exception InvalidApplicationException
> + * @throws BadStringOperationException when an invalid string
> + * operation is passed to a method for constructing a query
> + * @throws BadBinaryOpValueExpException when an invalid expression
> + * is passed to a method for constructing a query
> + * @throws BadAttributeValueExpException when an invalid MBean
> + * attribute is passed to a query constructing method
> + * @throws InvalidApplicationException when an invalid apply is
> attempted
> */
> public boolean apply(ObjectName name) throws
> BadStringOperationException, BadBinaryOpValueExpException,
> BadAttributeValueExpException, InvalidApplicationException ;
> ---
> old/src/java.management/share/classes/javax/management/StandardEmitterMBean.java
> 2015-04-15 19:40:42.559393236 -0700
> +++
> new/src/java.management/share/classes/javax/management/StandardEmitterMBean.java
> 2015-04-15 19:40:42.367489231 -0700
> @@ -91,6 +91,7 @@
> * that will have no effect on this object's
> * {@code getNotificationInfo()}.</p>
> *
> + * @param <T> the implementation type of the MBean
> * @param implementation the implementation of the MBean interface.
> * @param mbeanInterface a Standard MBean interface.
> * @param emitter the object that will handle notifications.
> @@ -129,6 +130,7 @@
> * that will have no effect on this object's
> * {@code getNotificationInfo()}.</p>
> *
> + * @param <T> the implementation type of the MBean
> * @param implementation the implementation of the MBean interface.
> * @param mbeanInterface a Standard MBean interface.
> * @param isMXBean If true, the {@code mbeanInterface} parameter
> ---
> old/src/java.management/share/classes/javax/management/StringValueExp.java
> 2015-04-15 19:40:43.015165247 -0700
> +++
> new/src/java.management/share/classes/javax/management/StringValueExp.java
> 2015-04-15 19:40:42.839253243 -0700
> @@ -95,11 +95,12 @@
> *
> * @return The <CODE>ValueExp</CODE>.
> *
> - * @exception BadStringOperationException
> - * @exception BadBinaryOpValueExpException
> - * @exception BadAttributeValueExpException
> - * @exception InvalidApplicationException
> + * @throws BadStringOperationException {@inheritDoc}
> + * @throws BadBinaryOpValueExpException {@inheritDoc}
> + * @throws BadAttributeValueExpException {@inheritDoc}
> + * @throws InvalidApplicationException {@inheritDoc}
> */
> + @Override
> public ValueExp apply(ObjectName name) throws
> BadStringOperationException, BadBinaryOpValueExpException,
> BadAttributeValueExpException, InvalidApplicationException {
> return this;
> ---
> old/src/java.management/share/classes/javax/management/ValueExp.java
> 2015-04-15 19:40:43.466939257 -0700
> +++
> new/src/java.management/share/classes/javax/management/ValueExp.java
> 2015-04-15 19:40:43.283031253 -0700
> @@ -80,10 +80,13 @@
> *
> * @return The <CODE>ValueExp</CODE>.
> *
> - * @exception BadStringOperationException
> - * @exception BadBinaryOpValueExpException
> - * @exception BadAttributeValueExpException
> - * @exception InvalidApplicationException
> + * @throws BadStringOperationException when an invalid string
> + * operation is passed to a method for constructing a query
> + * @throws BadBinaryOpValueExpException when an invalid expression
> + * is passed to a method for constructing a query
> + * @throws BadAttributeValueExpException when an invalid MBean
> + * attribute is passed to a query constructing method
> + * @throws InvalidApplicationException when an invalid apply is
> attempted
> */
> public ValueExp apply(ObjectName name)
> throws BadStringOperationException,
> BadBinaryOpValueExpException,
> ---
> old/src/java.management/share/classes/javax/management/modelmbean/ModelMBeanInfo.java
> 2015-04-15 19:40:43.930707268 -0700
> +++
> new/src/java.management/share/classes/javax/management/modelmbean/ModelMBeanInfo.java
> 2015-04-15 19:40:43.746799263 -0700
> @@ -307,6 +307,7 @@
>
> /**
> * Creates and returns a copy of this object.
> + * @return a copy of this object
> */
> public java.lang.Object clone();
>
> ---
> old/src/java.management/share/classes/javax/management/monitor/Monitor.java
> 2015-04-15 19:40:44.386479279 -0700
> +++
> new/src/java.management/share/classes/javax/management/monitor/Monitor.java
> 2015-04-15 19:40:44.198573274 -0700
> @@ -387,7 +387,7 @@
> *
> * @return The name of the monitor MBean registered.
> *
> - * @exception Exception
> + * @exception Exception if something goes wrong
> */
> public ObjectName preRegister(MBeanServer server, ObjectName name)
> throws Exception {
> @@ -416,7 +416,7 @@
> * <P>
> * Stops the monitor.
> *
> - * @exception Exception
> + * @exception Exception if something goes wrong
> */
> public void preDeregister() throws Exception {
>
> ---
> old/src/java.management/share/classes/javax/management/openmbean/ArrayType.java
> 2015-04-15 19:40:44.902221290 -0700
> +++
> new/src/java.management/share/classes/javax/management/openmbean/ArrayType.java
> 2015-04-15 19:40:44.670337285 -0700
> @@ -793,6 +793,7 @@
> * array type description = 3-dimension array of java.lang.String
> * }</pre>
> *
> + * @param <E> the Java type that described instances must have
> * @param elementType the <i>open type</i> of element values
> contained
> * in the arrays described by this
> <tt>ArrayType</tt>
> * instance; must be an instance of either
> @@ -800,7 +801,7 @@
> * <tt>TabularType</tt> or another
> <tt>ArrayType</tt>
> * with a <tt>SimpleType</tt>,
> <tt>CompositeType</tt>
> * or <tt>TabularType</tt> as its
> <tt>elementType</tt>.
> - *
> + * @return an {@code ArrayType} instance
> * @throws OpenDataException if <var>elementType's
> className</var> is not
> * one of the allowed Java class names
> for open
> * data.
> @@ -834,12 +835,14 @@
> * array type description = 3-dimension array of int
> * }</pre>
> *
> + * @param <T> the Java type that described instances must have
> * @param arrayClass a primitive array class such as {@code
> int[].class},
> * {@code boolean[][].class}, etc. The {@link
> * #getElementOpenType()} method of the returned
> * {@code ArrayType} returns the {@link
> SimpleType}
> * corresponding to the wrapper type of the
> primitive
> * type of the array.
> + * @return an {@code ArrayType} instance
> *
> * @throws IllegalArgumentException if <var>arrayClass</var> is not
> * a primitive array.
> ---
> old/src/java.management/share/classes/javax/management/timer/Timer.java 2015-04-15
> 19:40:45.397973302 -0700
> +++
> new/src/java.management/share/classes/javax/management/timer/Timer.java 2015-04-15
> 19:40:45.218063297 -0700
> @@ -195,7 +195,7 @@
> *
> * @return The name of the timer MBean registered.
> *
> - * @exception java.lang.Exception
> + * @exception java.lang.Exception if something goes wrong
> */
> public ObjectName preRegister(MBeanServer server, ObjectName name)
> throws java.lang.Exception {
> @@ -217,7 +217,7 @@
> * <P>
> * Stops the timer.
> *
> - * @exception java.lang.Exception
> + * @exception java.lang.Exception if something goes wrong
> */
> public void preDeregister() throws java.lang.Exception {
>
>
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic