8020318: Fix doclint issues in java.net

Reviewed-by: darcy, khazra

src/share/classes/java/net/CookieStore.java

 /*
- * Copyright (c) 2005, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2005, 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
@@ -75,6 +75,8 @@ public interface CookieStore {
      * @return          an immutable list of HttpCookie,
      *                  return empty list if no cookies match the given URI
      *
+     * @param uri       the uri associated with the cookies to be returned
+     *
      * @throws NullPointerException if <tt>uri</tt> is <tt>null</tt>
      *
      * @see #add

src/share/classes/java/net/HttpURLPermission.java

@@ -47,6 +47,7 @@ import java.security.Permission;
  * in {@link java.io.FilePermission}. There are three different ways
  * as the following examples show:
  * <table border>
+ * <caption>URL Examples</caption>
  * <tr><th>Example url</th><th>Description</th></tr>
  * <tr><td style="white-space:nowrap;">http://www.oracle.com/a/b/c.html</td>
  *   <td>A url which identifies a specific (single) resource</td>
@@ -57,7 +58,7 @@ import java.security.Permission;
  *       which only differ in the final path component, represented by the '*'.
  *   </td>
  * </tr>
- * <tr><td>http://www.oracle.com/a/b/-</li>
+ * <tr><td>http://www.oracle.com/a/b/-</td>
  *   <td>The '-' character refers to all resources recursively below the
  *       preceding path (eg. http://www.oracle.com/a/b/c/d/e.html matches this
  *       example).
@@ -164,6 +165,8 @@ public final class HttpURLPermission extends Permission {
      * methods and request headers by invoking the two argument
      * constructor as follows: HttpURLPermission(url, "*:*")
      *
+     * @param url the url string
+     *
      * @throws    IllegalArgumentException if url does not result in a valid {@link URI}
      */
     public HttpURLPermission(String url) {
@@ -204,11 +207,10 @@ public final class HttpURLPermission extends Permission {
      * <li>if the path or paths specified by p's url are contained in the
      *     set of paths specified by this's url, then return true
      * <li>otherwise, return false</li>
-     * </ol>
-     * <p>
-     * Some examples of how paths are matched are shown below:
-     * <p>
-     * <table border>
+     * </ul>
+     * <p>Some examples of how paths are matched are shown below:
+     * <p><table border>
+     * <caption>Examples of Path Matching</caption>
      * <tr><th>this's path</th><th>p's path</th><th>match</th></tr>
      * <tr><td>/a/b</td><td>/a/b</td><td>yes</td></tr>
      * <tr><td>/a/b/*</td><td>/a/b/c</td><td>yes</td></tr>

src/share/classes/java/net/Inet4Address.java

 /*
- * Copyright (c) 2000, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 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
@@ -36,7 +36,7 @@ import java.io.ObjectStreamException;
  * and <a href="http://www.ietf.org/rfc/rfc2365.txt"><i>RFC&nbsp;2365:
  * Administratively Scoped IP Multicast</i></a>
  *
- * <h4> <A NAME="format">Textual representation of IP addresses</a> </h4>
+ * <h3> <A NAME="format">Textual representation of IP addresses</a> </h3>
  *
  * Textual representation of IPv4 address used as input to methods
  * takes one of the following forms:

src/share/classes/java/net/Inet6Address.java

@@ -35,7 +35,7 @@ import java.util.Enumeration;
  * Defined by <a href="http://www.ietf.org/rfc/rfc2373.txt">
  * <i>RFC&nbsp;2373: IP Version 6 Addressing Architecture</i></a>.
  *
- * <h4> <A NAME="format">Textual representation of IP addresses</a> </h4>
+ * <h3> <A NAME="format">Textual representation of IP addresses</a> </h3>
  *
  * Textual representation of IPv6 address used as input to methods
  * takes one of the following forms:
@@ -156,7 +156,7 @@ import java.util.Enumeration;
  * system. Usually, the numeric values can be determined through administration
  * tools on the system. Each interface may have multiple values, one for each
  * scope. If the scope is unspecified, then the default value used is zero.</li>
- * <p><li><i>As a string.</i> This must be the exact string that is returned by
+ * <li><i>As a string.</i> This must be the exact string that is returned by
  * {@link java.net.NetworkInterface#getName()} for the particular interface in
  * question. When an Inet6Address is created in this way, the numeric scope-id
  * is determined at the time the object is created by querying the relevant

src/share/classes/java/net/InetAddress.java

 /*
- * Copyright (c) 1995, 2012, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 1995, 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
@@ -65,7 +65,7 @@ import sun.net.spi.nameservice.*;
  * with a host name or whether it has already done reverse host name
  * resolution).
  *
- * <h4> Address types </h4>
+ * <h3> Address types </h3>
  *
  * <blockquote><table cellspacing=2 summary="Description of unicast and multicast address types">
  *   <tr><th valign=top><i>unicast</i></th>
@@ -165,7 +165,6 @@ import sun.net.spi.nameservice.*;
  * <p>
  * A value of -1 indicates "cache forever".
  * </dd>
- * <p>
  * <dt><b>networkaddress.cache.negative.ttl</b> (default: 10)</dt>
  * <dd>Indicates the caching policy for un-successful name lookups
  * from the name service. The value is specified as as integer to

src/share/classes/java/net/ProtocolFamily.java

 /*
- * Copyright (c) 2007, 2008, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2007, 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,6 +34,8 @@ package java.net;
 public interface ProtocolFamily {
     /**
      * Returns the name of the protocol family.
+     *
+     * @return the name of the protocol family
      */
     String name();
 }

src/share/classes/java/net/SocketOption.java

 /*
- * Copyright (c) 2007, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2007, 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
@@ -45,11 +45,15 @@ public interface SocketOption<T> {
 
     /**
      * Returns the name of the socket option.
+     *
+     * @return the name of the socket option
      */
     String name();
 
     /**
      * Returns the type of the socket option value.
+     *
+     * @return the type of the socket option value
      */
     Class<T> type();
 }

src/share/classes/java/net/URI.java

 /*
- * Copyright (c) 2000, 2011, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2000, 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
@@ -61,13 +61,13 @@ import java.lang.NullPointerException;  // for javadoc
  * and relativizing URI instances.  Instances of this class are immutable.
  *
  *
- * <h4> URI syntax and components </h4>
+ * <h3> URI syntax and components </h3>
  *
  * At the highest level a URI reference (hereinafter simply "URI") in string
  * form has the syntax
  *
  * <blockquote>
- * [<i>scheme</i><tt><b>:</b></tt><i></i>]<i>scheme-specific-part</i>[<tt><b>#</b></tt><i>fragment</i>]
+ * [<i>scheme</i><tt><b>:</b></tt>]<i>scheme-specific-part</i>[<tt><b>#</b></tt><i>fragment</i>]
  * </blockquote>
  *
  * where square brackets [...] delineate optional components and the characters
@@ -334,14 +334,14 @@ import java.lang.NullPointerException;  // for javadoc
  *
  * <ul>
  *
- *   <li><p> The {@link #URI(java.lang.String) <code>single-argument
- *   constructor</code>} requires any illegal characters in its argument to be
+ *   <li><p> The {@linkplain #URI(java.lang.String) single-argument
+ *   constructor} requires any illegal characters in its argument to be
  *   quoted and preserves any escaped octets and <i>other</i> characters that
  *   are present.  </p></li>
  *
- *   <li><p> The {@link
+ *   <li><p> The {@linkplain
  *   #URI(java.lang.String,java.lang.String,java.lang.String,int,java.lang.String,java.lang.String,java.lang.String)
- *   <code>multi-argument constructors</code>} quote illegal characters as
+ *   multi-argument constructors} quote illegal characters as
  *   required by the components in which they appear.  The percent character
  *   (<tt>'%'</tt>) is always quoted by these constructors.  Any <i>other</i>
  *   characters are preserved.  </p></li>