8019407: Fix doclint issues in javax.naming.*

Reviewed-by: lancea

src/share/classes/javax/naming/CompositeName.java

 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -42,7 +42,7 @@ import java.util.Properties;
  * The most significant component is at index 0.
  * An empty composite name has no components.
  *<p>
- * <h4>JNDI Composite Name Syntax</h4>
+ * <h1>JNDI Composite Name Syntax</h1>
  * JNDI defines a standard string representation for composite names. This
  * representation is the concatenation of the components of a composite name
  * from left to right using the component separator (a forward
@@ -73,12 +73,12 @@ import java.util.Properties;
  * a separator) denotes a trailing empty component.
  * Adjacent component separators denote an empty component.
  *<p>
- *<h4>Composite Name Examples</h4>
+ *<h1>Composite Name Examples</h1>
  *This table shows examples of some composite names. Each row shows
  *the string form of a composite name and its corresponding structural form
  *(<tt>CompositeName</tt>).
  *<p>
-<table border="1" cellpadding=3 width="70%" summary="examples showing string form of composite name and its corresponding structural form (CompositeName)">
+<table border="1" cellpadding=3 summary="examples showing string form of composite name and its corresponding structural form (CompositeName)">
 
 <tr>
 <th>String Name</th>
@@ -137,14 +137,14 @@ import java.util.Properties;
 </tr>
 </table>
  * <p>
- *<h4>Composition Examples</h4>
+ *<h1>Composition Examples</h1>
  * Here are some composition examples.  The right column shows composing
  * string composite names while the left column shows composing the
  * corresponding <tt>CompositeName</tt>s.  Notice that composing the
  * string forms of two composite names simply involves concatenating
  * their string forms together.
 
-<p> <table border="1" cellpadding=3 width="70%" summary="composition examples showing string names and composite names">
+<p> <table border="1" cellpadding=3 summary="composition examples showing string names and composite names">
 
 <tr>
 <th>String Names</th>
@@ -189,7 +189,7 @@ import java.util.Properties;
 
 </table>
  *<p>
- *<h4>Multithreaded Access</h4>
+ *<h1>Multithreaded Access</h1>
  * A <tt>CompositeName</tt> instance is not synchronized against concurrent
  * multithreaded access. Multiple threads trying to access and modify a
  * <tt>CompositeName</tt> should lock the object.

src/share/classes/javax/naming/CompoundName.java

 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -39,7 +39,7 @@ import java.util.Properties;
  * The most significant component is at index 0.
  * An empty compound name has no components.
  *<p>
- * <h4>Compound Name Syntax</h4>
+ * <h1>Compound Name Syntax</h1>
  * The syntax of a compound name is specified using a set of properties:
  *<dl>
  *  <dt>jndi.syntax.direction
@@ -136,7 +136,7 @@ import java.util.Properties;
  * so that when the same string is parsed, it will yield the same components
  * of the original compound name.
  *<p>
- *<h4>Multithreaded Access</h4>
+ *<h1>Multithreaded Access</h1>
  * A <tt>CompoundName</tt> instance is not synchronized against concurrent
  * multithreaded access. Multiple threads trying to access and modify a
  * <tt>CompoundName</tt> should lock the object.

src/share/classes/javax/naming/Context.java

 /*
- * Copyright (c) 1999, 2006, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -32,7 +32,7 @@ import java.util.Hashtable;
  * consists of a set of name-to-object bindings.
  * It contains methods for examining and updating these bindings.
  * <p>
- * <h4>Names</h4>
+ * <h1>Names</h1>
  * Each name passed as an argument to a <tt>Context</tt> method is relative
  * to that context.  The empty name is used to name the context itself.
  * A name parameter may never be null.
@@ -69,12 +69,12 @@ import java.util.Hashtable;
  * names in a composite namespace, at the discretion of the service
  * provider.
  *<p>
- *<h4>Exceptions</h4>
+ *<h1>Exceptions</h1>
  * All the methods in this interface can throw a <tt>NamingException</tt> or
  * any of its subclasses. See <tt>NamingException</tt> and their subclasses
  * for details on each exception.
  *<p>
- *<h4>Concurrent Access</h4>
+ *<h1>Concurrent Access</h1>
  * A Context instance is not guaranteed to be synchronized against
  * concurrent access by multiple threads.  Threads that need to access
  * a single Context instance concurrently should synchronize amongst
@@ -91,7 +91,7 @@ import java.util.Hashtable;
  * being followed.
  *
  *<p>
- *<h4>Parameters</h4>
+ *<h1>Parameters</h1>
  * A <tt>Name</tt> parameter passed to any method of the
  * <tt>Context</tt> interface or one of its subinterfaces
  * will not be modified by the service provider.
@@ -103,7 +103,7 @@ import java.util.Hashtable;
  * The caller may subsequently modify it; the service provider may not.
  *
  *<p>
- *<h4>Environment Properties</h4>
+ *<h1>Environment Properties</h1>
  *<p>
  * JNDI applications need a way to communicate various preferences
  * and properties that define the environment in which naming and
@@ -138,7 +138,7 @@ import java.util.Hashtable;
  *
  *<p>
  *<a name=RESOURCEFILES></a>
- *<h4>Resource Files</h4>
+ *<h1>Resource Files</h1>
  *<p>
  * To simplify the task of setting up the environment
  * required by a JNDI application,
@@ -151,11 +151,11 @@ import java.util.Hashtable;
  * and the value is a string in the format defined
  * for that property.  Here is an example of a JNDI resource file:
  *
- * <blockquote><tt><pre>
+ * <blockquote>{@code
  * java.naming.factory.object=com.sun.jndi.ldap.AttrsToCorba:com.wiz.from.Person
  * java.naming.factory.state=com.sun.jndi.ldap.CorbaToAttrs:com.wiz.from.Person
  * java.naming.factory.control=com.sun.jndi.ldap.ResponseControlFactory
- * </pre></tt></blockquote>
+ * }</blockquote>
  *
  * The JNDI class library reads the resource files and makes the property
  * values freely available.  Thus JNDI resource files should be considered
@@ -165,7 +165,7 @@ import java.util.Hashtable;
  * There are two kinds of JNDI resource files:
  * <em>provider</em> and <em>application</em>.
  *
- * <h5>Provider Resource Files</h5>
+ * <h2>Provider Resource Files</h2>
  *
  * Each service provider has an optional resource that lists properties
  * specific to that provider.  The name of this resource is:
@@ -200,7 +200,7 @@ import java.util.Hashtable;
  * The service provider's documentation should clearly state which
  * properties are allowed; other properties in the file will be ignored.
  *
- * <h5>Application Resource Files</h5>
+ * <h2>Application Resource Files</h2>
  *
  * When an application is deployed, it will generally have several
  * codebase directories and JARs in its classpath.  Similarly, when an
@@ -232,7 +232,7 @@ import java.util.Hashtable;
  * collects and uses all of these export lists when searching for factory
  * classes.
  *
- * <h5>Search Algorithm for Properties</h5>
+ * <h2>Search Algorithm for Properties</h2>
  *
  * When JNDI constructs an initial context, the context's environment
  * is initialized with properties defined in the environment parameter

src/share/classes/javax/naming/InitialContext.java

 /*
- * Copyright (c) 1999, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -258,6 +258,7 @@ public class InitialContext implements Context {
      * environment may be modified independently and it may be accessed
      * concurrently).
      *
+     * @param <T> the type of the returned object
      * @param name
      *          the name of the object to look up
      * @return  the object bound to <tt>name</tt>
@@ -276,6 +277,7 @@ public class InitialContext implements Context {
    /**
      * A static method to retrieve the named object.
      * See {@link #doLookup(Name)} for details.
+     * @param <T> the type of the returned object
      * @param name
      *          the name of the object to look up
      * @return  the object bound to <tt>name</tt>

src/share/classes/javax/naming/RefAddr.java

 /*
- * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -91,7 +91,8 @@ public abstract class RefAddr implements java.io.Serializable {
       * Determines whether obj is equal to this RefAddr.
       *<p>
       * obj is equal to this RefAddr all of these conditions are true
-      *<ul> non-null
+      *<ul>
+      *<li> non-null
       *<li> instance of RefAddr
       *<li> obj has the same address type as this RefAddr (using String.compareTo())
       *<li> both obj and this RefAddr's contents are null or they are equal

src/share/classes/javax/naming/ReferralException.java

 /*
- * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -38,7 +38,7 @@ import java.util.Hashtable;
  * constructors and/or corresponding "set" methods).
  * <p>
  * The following code sample shows how <tt>ReferralException</tt> can be used.
- * <p><blockquote><pre>
+ * <blockquote>{@code
  *      while (true) {
  *          try {
  *              bindings = ctx.listBindings(name);
@@ -51,7 +51,7 @@ import java.util.Hashtable;
  *              ctx = e.getReferralContext();
  *          }
  *      }
- * </pre></blockquote></p>
+ * }</blockquote>
  *<p>
  * <tt>ReferralException</tt> is an abstract class. Concrete implementations
  * determine its synchronization and serialization properties.

src/share/classes/javax/naming/directory/DirContext.java

 /*
- * Copyright (c) 1999, 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -32,7 +32,7 @@ import javax.naming.*;
  * methods for examining and updating attributes
  * associated with objects, and for searching the directory.
  * <p>
- * <h4>Names</h4>
+ * <h1>Names</h1>
  * Each name passed as an argument to a <tt>DirContext</tt> method is relative
  * to that context.  The empty name is used to name the context itself.
  * The name parameter may never be null.
@@ -51,7 +51,7 @@ import javax.naming.*;
  * name argument to the <tt>Context</tt> methods. These same rules
  * apply to the name argument to the <tt>DirContext</tt> methods.
  * <p>
- * <h4>Attribute Models</h4>
+ * <h1>Attribute Models</h1>
  * There are two basic models of what attributes should be
  * associated with.  First, attributes may be directly associated with a
  * DirContext object.
@@ -81,7 +81,7 @@ import javax.naming.*;
  * whether an object's attributes are stored as part of the object, or stored
  * within the parent object and associated with the object's name.
  * <p>
- * <h4>Attribute Type Names</h4>
+ * <h1>Attribute Type Names</h1>
  * In the <tt>getAttributes()</tt> and <tt>search()</tt> methods,
  * you can supply the attributes to return by supplying a list of
  * attribute names (strings).
@@ -113,7 +113,7 @@ import javax.naming.*;
  * </ul>
  *
  * <p>
- *<h4>Operational Attributes</h4>
+ *<h1>Operational Attributes</h1>
  *<p>
  * Some directories have the notion of "operational attributes" which are
  * attributes associated with a directory object for administrative
@@ -127,7 +127,7 @@ import javax.naming.*;
  * In order to retrieve operational attributes, you must name them explicitly.
  *
  * <p>
- * <h4>Named Context</h4>
+ * <h1>Named Context</h1>
  * <p>
  * There are certain methods in which the name must resolve to a context
  * (for example, when searching a single level context). The documentation
@@ -138,7 +138,7 @@ import javax.naming.*;
  * Aside from these methods, there is no requirement that the
  * <em>named object</em> be a DirContext.
  *<p>
- *<h4>Parameters</h4>
+ *<h1>Parameters</h1>
  *<p>
  * An <tt>Attributes</tt>, <tt>SearchControls</tt>, or array object
  * passed as a parameter to any method will not be modified by the
@@ -150,7 +150,7 @@ import javax.naming.*;
  * the caller.  The caller may subsequently modify it; the service
  * provider will not.
  *<p>
- *<h4>Exceptions</h4>
+ *<h1>Exceptions</h1>
  *<p>
  * All the methods in this interface can throw a NamingException or
  * any of its subclasses. See NamingException and their subclasses

src/share/classes/javax/naming/event/EventContext.java

 /*
- * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -34,7 +34,7 @@ import javax.naming.NamingException;
  * Contains methods for registering/deregistering listeners to be notified of
  * events fired when objects named in a context changes.
  *<p>
- *<h4>Target</h4>
+ *<h1>Target</h1>
  * The name parameter in the <tt>addNamingListener()</tt> methods is referred
  * to as the <em>target</em>. The target, along with the scope, identify
  * the object(s) that the listener is interested in.
@@ -59,7 +59,7 @@ import javax.naming.NamingException;
  * whether a <tt>EventContext</tt> supports registration
  * of nonexistent targets.
  *<p>
- *<h4>Event Source</h4>
+ *<h1>Event Source</h1>
  * The <tt>EventContext</tt> instance on which you invoke the
  * registration methods is the <em>event source</em> of the events that are
  * (potentially) generated.
@@ -93,7 +93,7 @@ import javax.naming.NamingException;
  * it needs to keep a reference to the listener in order to remove it
  * later). It cannot expect to do a <tt>lookup()</tt> and get another instance of
  * a <tt>EventContext</tt> on which to perform the deregistration.
- *<h4>Lifetime of Registration</h4>
+ *<h1>Lifetime of Registration</h1>
  * A registered listener becomes deregistered when:
  *<ul>
  *<li>It is removed using <tt>removeNamingListener()</tt>.
@@ -105,7 +105,7 @@ import javax.naming.NamingException;
  * Until that point, a <tt>EventContext</tt> instance that has outstanding
  * listeners will continue to exist and be maintained by the service provider.
  *
- *<h4>Listener Implementations</h4>
+ *<h1>Listener Implementations</h1>
  * The registration/deregistration methods accept an instance of
  * <tt>NamingListener</tt>. There are subinterfaces of <tt>NamingListener</tt>
  * for different of event types of <tt>NamingEvent</tt>.
@@ -118,7 +118,7 @@ import javax.naming.NamingException;
  * of the listeners, this allows some service providers to optimize the
  * registration.
  *
- *<h4>Threading Issues</h4>
+ *<h1>Threading Issues</h1>
  *
  * Like <tt>Context</tt> instances in general, instances of
  * <tt>EventContext</tt> are not guaranteed to be thread-safe.

src/share/classes/javax/naming/ldap/ControlFactory.java

 /*
- * Copyright (c) 1999, 2010, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -51,7 +51,7 @@ import com.sun.naming.internal.ResourceManager;
   */
 
 public abstract class ControlFactory {
-    /*
+    /**
      * Creates a new instance of a control factory.
      */
     protected ControlFactory() {

src/share/classes/javax/naming/ldap/InitialLdapContext.java

@@ -38,7 +38,7 @@ import java.util.Hashtable;
   * <tt>javax.naming.InitialDirContext</tt> for details on synchronization,
   * and the policy for how an initial context is created.
   *
-  * <h4>Request Controls</h4>
+  * <h1>Request Controls</h1>
   * When you create an initial context (<tt>InitialLdapContext</tt>),
   * you can specify a list of request controls.
   * These controls will be used as the request controls for any

src/share/classes/javax/naming/ldap/LdapContext.java

 /*
- * Copyright (c) 1999, 2000, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.
  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
  *
  * This code is free software; you can redistribute it and/or modify it
@@ -78,10 +78,8 @@ import java.util.Hashtable;
  * <h4>Context Request Controls</h4>
  * There are two ways in which a context instance gets its request controls:
  * <ol>
- * <tt>
- * <li>ldapContext.newInstance(<strong>reqCtls</strong>)
- * <li>ldapContext.setRequestControls(<strong>reqCtls</strong>)
- * </tt>
+ * <li><tt>ldapContext.newInstance(<strong>reqCtls</strong>)</tt>
+ * <li><tt>ldapContext.setRequestControls(<strong>reqCtls</strong>)</tt>
  * </ol>
  * where <tt>ldapContext</tt> is an instance of <tt>LdapContext</tt>.
  * Specifying <tt>null</tt> or an empty array for <tt>reqCtls</tt>
@@ -102,12 +100,10 @@ import java.util.Hashtable;
  * <h4>Connection Request Controls</h4>
  * There are three ways in which connection request controls are set:
  * <ol>
- * <tt>
- * <li>
- * new InitialLdapContext(env, <strong>connCtls</strong>)
- * <li>refException.getReferralContext(env, <strong>connCtls</strong>)
- * <li>ldapContext.reconnect(<strong>connCtls</strong>);
- * </tt>
+ * <li><tt>
+ * new InitialLdapContext(env, <strong>connCtls</strong>)</tt>
+ * <li><tt>refException.getReferralContext(env, <strong>connCtls</strong>)</tt>
+ * <li><tt>ldapContext.reconnect(<strong>connCtls</strong>);</tt>
  * </ol>
  * where <tt>refException</tt> is an instance of
  * <tt>LdapReferralException</tt>, and <tt>ldapContext</tt> is an