Assorted javadoc updates. Add more explicit error conditions often assocaited with passing null, require IllegalArgument/IlleglStateExceptions to be thrown.

svn path=/trunk/; revision=486
diff --git a/src/jsr311-api/src/javax/ws/rs/Consumes.java b/src/jsr311-api/src/javax/ws/rs/Consumes.java
index c8ed9e8..fe74d6a 100644
--- a/src/jsr311-api/src/javax/ws/rs/Consumes.java
+++ b/src/jsr311-api/src/javax/ws/rs/Consumes.java
@@ -26,8 +26,8 @@
 import java.lang.annotation.Target;
 
 /**
- * Defines the media types that the methods of a resource class or MessageBodyReader
- * can accept. If
+ * Defines the media types that the methods of a resource class or 
+ * {@link javax.ws.rs.ext.MessageBodyReader} can accept. If
  * not specified, a container will assume that any media type is acceptable.
  * Method level annotations override a class level annotation. A container
  * is responsible for ensuring that the method invoked is capable of consuming
diff --git a/src/jsr311-api/src/javax/ws/rs/FormParam.java b/src/jsr311-api/src/javax/ws/rs/FormParam.java
index 0da56a2..00f8b0b 100644
--- a/src/jsr311-api/src/javax/ws/rs/FormParam.java
+++ b/src/jsr311-api/src/javax/ws/rs/FormParam.java
@@ -29,8 +29,8 @@
  * to a resource method parameter. Values are URL decoded unless this is
  * disabled using the {@link Encoded} annotation. A default value can be
  * specified using the {@link DefaultValue} annotation.
- * If the request entity body is absent or is of any media type other than 
- * application/x-www-form-urlencoded, the default value is used.
+ * If the request entity body is absent or is an unsupported media type, the
+ * default value is used.
  * 
  * The type <code>T</code> of the annotated parameter must either:
  * <ol>
diff --git a/src/jsr311-api/src/javax/ws/rs/Produces.java b/src/jsr311-api/src/javax/ws/rs/Produces.java
index cdb10fc..9e68ab8 100644
--- a/src/jsr311-api/src/javax/ws/rs/Produces.java
+++ b/src/jsr311-api/src/javax/ws/rs/Produces.java
@@ -27,7 +27,7 @@
 
 /**
  * Defines the media type(s) that the methods of a resource class or
- * MessageBodyWriter can produce.
+ * {@link javax.ws.rs.ext.MessageBodyWriter} can produce.
  * If not specified then a container will assume that any type can be produced.
  * Method level annotations override a class level annotation. A container
  * is responsible for ensuring that the method invoked is capable of producing
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Application.java b/src/jsr311-api/src/javax/ws/rs/core/Application.java
index 55368f4..b03f1d7 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/Application.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/Application.java
@@ -32,25 +32,29 @@
      * <p>Implementations should warn about and ignore classes that do not 
      * conform to the requirements of root resource or provider classes.
      * Implementations should warn about and ignore classes for which
-     * {@link #getSingletons()} returns an instance.</p>
+     * {@link #getSingletons()} returns an instance. Implementations MUST
+     * NOT modify the returned set.</p>
      * 
-     * @return a set of root resource and provider classes.
+     * @return a set of root resource and provider classes. Returning null
+     * is equivalent to returning an empty set.
      */
     public abstract Set<Class<?>> getClasses();
     
     /**
      * Get a set of root resource and provider instances. Fields and properties
      * of returned instances are injected with their declared dependencies
-     * (see {@link Context}) prior to use.
+     * (see {@link Context}) by the runtime prior to use.
      * 
      * <p>Implementations should warn about and ignore classes that do not
      * conform to the requirements of root resource or provider classes.
      * Implementations should flag an error if the returned set includes
-     * more than one instance of the same class.</p>
+     * more than one instance of the same class. Implementations MUST
+     * NOT modify the returned set.</p>
      * 
      * <p>The default implementation returns an empty set.</p>
      * 
-     * @return a set of root resource and provider instances.
+     * @return a set of root resource and provider instances. Returning null
+     * is equivalent to returning an empty set.
      */
     public Set<Object> getSingletons() {
         return emptySet;
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Cookie.java b/src/jsr311-api/src/javax/ws/rs/core/Cookie.java
index b0fd887..4b8742e 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/Cookie.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/Cookie.java
@@ -163,7 +163,7 @@
 
     /**
      * Compare for equality
-     * @param obj
+     * @param obj the object to compare to
      * @return true if the object is a {@code Cookie} with the same value for
      * all properties, false otherwise.
      */
diff --git a/src/jsr311-api/src/javax/ws/rs/core/MediaType.java b/src/jsr311-api/src/javax/ws/rs/core/MediaType.java
index ca2328b..e25ef0f 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/MediaType.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/MediaType.java
@@ -83,6 +83,11 @@
     /** "application/x-www-form-urlencoded" */
     public final static MediaType APPLICATION_FORM_URLENCODED_TYPE = new MediaType("application","x-www-form-urlencoded");
 
+    /** "multipart/form-data" */
+    public final static String MULTIPART_FORM_DATA = "multipart/form-data";
+    /** "multipart/form-data" */
+    public final static MediaType MULTIPART_FORM_DATA_TYPE = new MediaType("multipart","form-data");
+
     /** "application/octet-stream" */
     public final static String APPLICATION_OCTET_STREAM = "application/octet-stream";
     /** "application/octet-stream" */
@@ -117,9 +122,12 @@
     /**
      * Creates a new instance of MediaType with the supplied type, subtype and
      * parameters. 
-     * @param type the primary type
-     * @param subtype the subtype
-     * @param parameters a map of media type parameters
+     * @param type the primary type, null is equivalent to 
+     * {@link #MEDIA_TYPE_WILDCARD}.
+     * @param subtype the subtype, null is equivalent to 
+     * {@link #MEDIA_TYPE_WILDCARD}.
+     * @param parameters a map of media type parameters, null is the same as an
+     * empty map.
      */
     public MediaType(String type, String subtype, Map<String, String> parameters) {
         this.type = type==null ? MEDIA_TYPE_WILDCARD : type;
@@ -141,8 +149,10 @@
     
     /**
      * Creates a new instance of MediaType with the supplied type and subtype.
-     * @param type the primary type
-     * @param subtype the subtype
+     * @param type the primary type, null is equivalent to 
+     * {@link #MEDIA_TYPE_WILDCARD}
+     * @param subtype the subtype, null is equivalent to 
+     * {@link #MEDIA_TYPE_WILDCARD}
      */
     public MediaType(String type, String subtype) {
         this(type,subtype,emptyMap);
diff --git a/src/jsr311-api/src/javax/ws/rs/core/NewCookie.java b/src/jsr311-api/src/javax/ws/rs/core/NewCookie.java
index 90d9621..83ede1e 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/NewCookie.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/NewCookie.java
@@ -90,6 +90,7 @@
     /**
      * Create a new instance copying the information in the supplied cookie.
      * @param cookie the cookie to clone
+     * @throws IllegalArgumentException if cookie is null
      */
     public NewCookie(Cookie cookie) {
         super(cookie.getName(), cookie.getValue(), cookie.getPath(), cookie.getDomain(), cookie.getVersion());
@@ -101,6 +102,7 @@
      * @param comment the comment
      * @param maxAge the maximum age of the cookie in seconds
      * @param secure specifies whether the cookie will only be sent over a secure connection
+     * @throws IllegalArgumentException if cookie is null
      */
     public NewCookie(Cookie cookie, String comment, int maxAge, boolean secure) {
         this(cookie.getName(), cookie.getValue(), cookie.getPath(), cookie.getDomain(), cookie.getVersion(), comment, maxAge, secure);
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Request.java b/src/jsr311-api/src/javax/ws/rs/core/Request.java
index 4c02702..e17fa0f 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/Request.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/Request.java
@@ -60,7 +60,7 @@
      * available representation variants.
      * @return the variant that best matches the request.
      * @see Variant.VariantListBuilder
-     * @throws IllegalArgumentException if variants is empty
+     * @throws java.lan.IllegalArgumentException if variants is empty or null
      * @throws java.lang.IllegalStateException if called outside the scope of a request
      */
     Variant selectVariant(List<Variant> variants) throws IllegalArgumentException;
@@ -72,6 +72,7 @@
      * @return null if the preconditions are met or a ResponseBuilder set with
      * the appropriate status if the preconditions are not met. A returned
      * ResponseBuilder will include an ETag header set with the value of eTag.
+     * @throws java.lang.IllegalArgumentException if eTag is null
      * @throws java.lang.IllegalStateException if called outside the scope of a request
      */
     ResponseBuilder evaluatePreconditions(EntityTag eTag);
@@ -82,6 +83,7 @@
      * @param lastModified a date that specifies the modification date of the resource
      * @return null if the preconditions are met or a ResponseBuilder set with
      * the appropriate status if the preconditions are not met.
+     * @throws java.lang.IllegalArgumentException if lastModified is null
      * @throws java.lang.IllegalStateException if called outside the scope of a request
      */
     ResponseBuilder evaluatePreconditions(Date lastModified);
@@ -94,6 +96,7 @@
      * @return null if the preconditions are met or a ResponseBuilder set with
      * the appropriate status if the preconditions are not met.  A returned
      * ResponseBuilder will include an ETag header set with the value of eTag.
+     * @throws java.lang.IllegalArgumentException if lastModified or eTag is null
      * @throws java.lang.IllegalStateException if called outside the scope of a request
      */
     ResponseBuilder evaluatePreconditions(Date lastModified, EntityTag eTag);
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Response.java b/src/jsr311-api/src/javax/ws/rs/core/Response.java
index 1d875bb..2ba60b1 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/Response.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/Response.java
@@ -57,7 +57,7 @@
     
     /**
      * Get the status code associated with the response.
-     * @return the response status code or -1 if the status was not set
+     * @return the response status code or -1 if the status was not set.  
      */
     public abstract int getStatus();
 
@@ -110,6 +110,8 @@
      * Create a new ResponseBuilder with the supplied status.
      * @param status the response status
      * @return a new ResponseBuilder
+     * @throws IllegalArgumentException if status is less than 100 or greater
+     * than 599.
      */
     public static ResponseBuilder status(int status) {
         ResponseBuilder b = ResponseBuilder.newInstance();
@@ -128,9 +130,9 @@
     }
 
     /**
-     * Create a new ResponseBuilder that contains a representation. Wrap the 
-     * actual entity with {@link GenericEntity} if the generic type should be
-     * preserved.
+     * Create a new ResponseBuilder that contains a representation. It is the
+     * callers responsibility to wrap the actual entity with
+     * {@link GenericEntity} if preservation of its generic type is required.
      * 
      * @param entity the representation entity data
      * @return a new ResponseBuilder
@@ -142,9 +144,9 @@
     }
 
     /**
-     * Create a new ResponseBuilder that contains a representation. If
-     * required, wrap the actual entity with {@link GenericEntity} to preserve
-     * the generic type.
+     * Create a new ResponseBuilder that contains a representation. It is the
+     * callers responsibility to wrap the actual entity with
+     * {@link GenericEntity} if preservation of its generic type is required.
      * 
      * @param entity the representation entity data
      * @param type the media type of the entity
@@ -158,9 +160,9 @@
     }
 
     /**
-     * Create a new ResponseBuilder that contains a representation. If
-     * required, wrap the actual entity with {@link GenericEntity} to preserve
-     * the generic type.
+     * Create a new ResponseBuilder that contains a representation. It is the
+     * callers responsibility to wrap the actual entity with
+     * {@link GenericEntity} if preservation of its generic type is required.
      * 
      * @param entity the representation entity data
      * @param type the media type of the entity
@@ -174,9 +176,9 @@
     }
 
     /**
-     * Create a new ResponseBuilder that contains a representation. If
-     * required, wrap the actual entity with {@link GenericEntity} to preserve
-     * the generic type.
+     * Create a new ResponseBuilder that contains a representation. It is the
+     * callers responsibility to wrap the actual entity with
+     * {@link GenericEntity} if preservation of its generic type is required.
      * 
      * @param entity the representation entity data
      * @param variant representation metadata
@@ -207,6 +209,7 @@
      * supplied it will be converted into an absolute URI by resolving it
      * relative to the request URI (see {@link UriInfo#getRequestUri}).
      * @return a new ResponseBuilder
+     * @throws java.lang.IllegalArgumentException if location is null
      */
     public static ResponseBuilder created(URI location) {
         ResponseBuilder b = status(Status.CREATED).location(location);
@@ -238,6 +241,7 @@
      * 
      * @param tag a tag for the unmodified entity
      * @return a new ResponseBuilder
+     * @throws java.lang.IllegalArgumentException if tag is null
      */
     public static ResponseBuilder notModified(EntityTag tag) {
         ResponseBuilder b = notModified();
@@ -253,6 +257,7 @@
      * @param tag the string content of a strong entity tag. The JAX-RS
      * runtime will quote the supplied value when creating the header.
      * @return a new ResponseBuilder
+     * @throws java.lang.IllegalArgumentException if tag is null
      */
     public static ResponseBuilder notModified(String tag) {
         ResponseBuilder b = notModified();
@@ -269,6 +274,7 @@
      * relative to the base URI of the application (see 
      * {@link UriInfo#getBaseUri}).
      * @return a new ResponseBuilder
+     * @throws java.lang.IllegalArgumentException if location is null
      */
     public static ResponseBuilder seeOther(URI location) {
         ResponseBuilder b = status(Status.SEE_OTHER).location(location);
@@ -283,6 +289,7 @@
      * relative to the base URI of the application (see 
      * {@link UriInfo#getBaseUri}).
      * @return a new ResponseBuilder
+     * @throws java.lang.IllegalArgumentException if location is null
      */
     public static ResponseBuilder temporaryRedirect(URI location) {
         ResponseBuilder b = status(Status.TEMPORARY_REDIRECT).location(location);
@@ -292,7 +299,8 @@
     /**
      * Create a new ResponseBuilder for a not acceptable response.
      * 
-     * @param variants list of variants that were available
+     * @param variants list of variants that were available, a null vaue is
+     * equivalent to an empty list.
      * @return a new ResponseBuilder
      */
     public static ResponseBuilder notAcceptable(List<Variant> variants) {
@@ -359,6 +367,8 @@
          * 
          * @param status the response status
          * @return the updated ResponseBuilder
+         * @throws IllegalArgumentException if status is less than 100 or greater
+         * than 599.
          */
         public abstract ResponseBuilder status(int status);
         
@@ -376,8 +386,9 @@
         };
         
         /**
-         * Set the entity on the ResponseBuilder. If required, wrap the actual
-         * entity with {@link GenericEntity} to preserve the generic type.
+         * Set the entity on the ResponseBuilder. It is the
+         * callers responsibility to wrap the actual entity with
+         * {@link GenericEntity} if preservation of its generic type is required.
          * 
          * @param entity the response entity
          * @return the updated ResponseBuilder
@@ -405,8 +416,8 @@
         /**
          * Set representation metadata on the ResponseBuilder.
          * 
-         * 
-         * @param variant metadata of the response entity
+         * @param variant metadata of the response entity a null value is
+         * equivalent to a variant with all null properties
          * @return the updated ResponseBuilder
          */
         public abstract ResponseBuilder variant(Variant variant);
@@ -414,7 +425,8 @@
         /**
          * Add a Vary header that lists the available variants.
          * 
-         * @param variants a list of available representation variants
+         * @param variants a list of available representation variants, a null
+         * value is equivalent to an empty list.
          * @return the updated ResponseBuilder
          */
         public abstract ResponseBuilder variants(List<Variant> variants);
@@ -422,7 +434,6 @@
         /**
          * Set the language on the ResponseBuilder.
          * 
-         * 
          * @param language the language of the response entity
          * @return the updated ResponseBuilder
          */
diff --git a/src/jsr311-api/src/javax/ws/rs/core/StreamingOutput.java b/src/jsr311-api/src/javax/ws/rs/core/StreamingOutput.java
index e9c2dd6..55ce194 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/StreamingOutput.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/StreamingOutput.java
@@ -39,7 +39,7 @@
      * @throws java.io.IOException if an IO error is encountered
      * @throws javax.ws.rs.WebApplicationException if a specific 
      * HTTP error response needs to be produced. Only effective if thrown prior
-     * to the response being committed.
+     * to any bytes being written to output.
      */
     void write(OutputStream output) throws IOException, WebApplicationException; 
 }
diff --git a/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java b/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
index e17a3b1..f9227a2 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/UriInfo.java
@@ -86,8 +86,7 @@
     public List<PathSegment> getPathSegments(boolean decode);
     
     /**
-     * Get the absolute request URI. This includes query parameters and
-     * any supplied fragment.
+     * Get the absolute request URI including any query parameters.
      * @return the absolute request URI
      * @throws java.lang.IllegalStateException if called outside the scope of a request
      */
@@ -102,7 +101,7 @@
     
     /**
      * Get the absolute path of the request. This includes everything preceding
-     * the path (host, port etc) but excludes query parameters and fragment.
+     * the path (host, port etc) but excludes query parameters.
      * This is a shortcut for
      * <code>uriInfo.getBase().resolve(uriInfo.getPath()).</code>
      * @return the absolute path of the request
@@ -113,7 +112,7 @@
     /**
      * Get the absolute path of the request in the form of a UriBuilder.
      * This includes everything preceding the path (host, port etc) but excludes
-     * query parameters and fragment.
+     * query parameters.
      * @return a UriBuilder initialized with the absolute path of the request
      * @throws java.lang.IllegalStateException if called outside the scope of a request
      */
diff --git a/src/jsr311-api/src/javax/ws/rs/core/Variant.java b/src/jsr311-api/src/javax/ws/rs/core/Variant.java
index 4e7f27b..b8df85c 100644
--- a/src/jsr311-api/src/javax/ws/rs/core/Variant.java
+++ b/src/jsr311-api/src/javax/ws/rs/core/Variant.java
@@ -38,6 +38,8 @@
      * @param mediaType the media type of the variant - may be null
      * @param language the language of the variant - may be null
      * @param encoding the content encoding of the variant - may be null
+     * @throws java.lang.IllegalArgumentException if all three parameters are
+     * null
      */
     public Variant(MediaType mediaType, Locale language, String encoding) {
         this.encoding = encoding;
@@ -76,6 +78,8 @@
      * are supported they should be included as parameters of the respective
      * media type.
      * @return the initailized builder
+     * @throws java.lang.IllegalArgumentException if mediaTypes is null or
+     * contains no elements.
      */
     public static VariantListBuilder mediaTypes(MediaType... mediaTypes) {
         VariantListBuilder b = VariantListBuilder.newInstance();
@@ -88,6 +92,8 @@
      * languages.
      * @param languages the available languages.
      * @return the initailized builder
+     * @throws java.lang.IllegalArgumentException if languages is null or
+     * contains no elements.
      */
     public static VariantListBuilder languages(Locale... languages) {
         VariantListBuilder b = VariantListBuilder.newInstance();
@@ -100,6 +106,8 @@
      * encodings.
      * @param encodings the available encodings.
      * @return the initailized builder
+     * @throws java.lang.IllegalArgumentException if encodings is null or
+     * contains no elements.
      */
     public static VariantListBuilder encodings(String... encodings) {
         VariantListBuilder b = VariantListBuilder.newInstance();
@@ -197,8 +205,9 @@
          * <p><pre>List<Variant> list = VariantListBuilder.newInstance().languages("en","fr")
          *   .encodings("zip", "identity").add().build()</pre>
          * 
-         * 
          * @return the updated builder
+         * @throws java.lang.IllegalStateException if there is not at least one
+         * mediaType, language or encoding set for the current variant.
          */
         public abstract VariantListBuilder add();
         
diff --git a/src/jsr311-api/src/javax/ws/rs/ext/Providers.java b/src/jsr311-api/src/javax/ws/rs/ext/Providers.java
index d553fd8..ef2a51d 100644
--- a/src/jsr311-api/src/javax/ws/rs/ext/Providers.java
+++ b/src/jsr311-api/src/javax/ws/rs/ext/Providers.java
@@ -38,9 +38,9 @@
      * Get a message body reader that matches a set of criteria. The set of
      * readers is first filtered by comparing the supplied value of
      * {@code mediaType} with the value of each reader's 
-     * {@link javax.ws.rs.Consumes}, comparing the supplied value of
-     * {@code type} with the generic type of the reader, and eliminating those 
-     * that do not match.
+     * {@link javax.ws.rs.Consumes}, ensuring the supplied value of
+     * {@code type} is assignable to the generic type of the reader, and 
+     * eliminating those that do not match.
      * The list of matching readers is then ordered with those with the best 
      * matching values of {@link javax.ws.rs.Consumes} (x/y > x&#47;* > *&#47;*)
      * sorted first. Finally, the 
@@ -48,6 +48,7 @@
      * method is called on each reader in order using the supplied criteria and
      * the first reader that returns {@code true} is selected and returned.
      * 
+     * @param type the class of object that is to be written.
      * @param mediaType the media type of the data that will be read.
      * @param genericType the type of object to be produced. E.g. if the 
      * message body is to be converted into a method parameter, this will be
@@ -68,9 +69,9 @@
      * Get a message body writer that matches a set of criteria. The set of
      * writers is first filtered by comparing the supplied value of
      * {@code mediaType} with the value of each writer's 
-     * {@link javax.ws.rs.Produces}, comparing the supplied value of
-     * {@code type} with the generic type of the writer, and eliminating those
-     * that do not match.
+     * {@link javax.ws.rs.Produces}, ensuring the supplied value of
+     * {@code type} is assignable to the generic type of the reader, and 
+     * eliminating those that do not match.
      * The list of matching writers is then ordered with those with the best 
      * matching values of {@link javax.ws.rs.Produces} (x/y > x&#47;* > *&#47;*)
      * sorted first. Finally, the 
@@ -109,11 +110,11 @@
      * Get a context resolver for a particular type of context and media type.
      * The set of resolvers is first filtered by comparing the supplied value of
      * {@code mediaType} with the value of each resolver's 
-     * {@link javax.ws.rs.Produces}, comparing the supplied value of
-     * {@code type} with the generic type of the resolver, and eliminating those
-     * that do not match. If only one resolver matches the criteria then it is
-     * returned. If more than one resolver matches then the list of matching 
-     * resolvers is ordered with those with the best 
+     * {@link javax.ws.rs.Produces}, ensuring the generic type of the context 
+     * resolver is assignable to the supplied value of {@code contextType}, and 
+     * eliminating those that do not match. If only one resolver matches the 
+     * criteria then it is returned. If more than one resolver matches then the
+     * list of matching resolvers is ordered with those with the best 
      * matching values of {@link javax.ws.rs.Produces} (x/y > x&#47;* > *&#47;*)
      * sorted first. A proxy is returned that delegates calls to
      * {@link ContextResolver#getContext(java.lang.Class)} to each matching context
diff --git a/src/jsr311-api/src/javax/ws/rs/ext/RuntimeDelegate.java b/src/jsr311-api/src/javax/ws/rs/ext/RuntimeDelegate.java
index cbf5511..7ee70dc 100644
--- a/src/jsr311-api/src/javax/ws/rs/ext/RuntimeDelegate.java
+++ b/src/jsr311-api/src/javax/ws/rs/ext/RuntimeDelegate.java
@@ -133,8 +133,7 @@
     }
     
     /**
-     * Create a new instance of a {@link javax.ws.rs.core.UriBuilder} with 
-     * automatic encoding enabled.
+     * Create a new instance of a {@link javax.ws.rs.core.UriBuilder}.
      * @return new UriBuilder instance
      * @see javax.ws.rs.core.UriBuilder
      */
@@ -162,8 +161,8 @@
      * @param application the application configuration
      * @param endpointType the type of endpoint instance to be created. 
      * @return a configured instance of the requested type.
-     * @throws java.lang.IllegalArgumentException if the requested endpoint
-     * type is not supported.
+     * @throws java.lang.IllegalArgumentException if application is null or the
+     * requested endpoint type is not supported.
      * @throws java.lang.UnsupportedOperationException if the implementation
      * supports no endpoint types.
      */
@@ -173,9 +172,12 @@
     /**
      * Obtain an instance of a HeaderDelegate for the supplied class. An 
      * implementation is required to support the following values for type:
-     * Cookie, CacheControl, EntityTag, NewCookie, MediaType, Date.
+     * {@link javax.ws.rs.core.Cookie}, {@link javax.ws.rs.core.CacheControl},
+     * {@link javax.ws.rs.core.EntityTag}, {@link javax.ws.rs.core.NewCookie}, 
+     * {@link javax.ws.rs.core.MediaType} and {@code java.util.Date}.
      * @param type the class of the header
      * @return an instance of HeaderDelegate for the supplied type
+     * @throws java.lang.IllegalArgumentException if type is null
      */
     public abstract <T> HeaderDelegate<T> createHeaderDelegate(Class<T> type);