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 {
