Improve the javadoc for the API. (#33)

* Some code extracts had strange spacing because of longstanding bugs in the javadoc tool.

* Most javadoc warnings have been fixed, often at the cost of annoyingly redundant
  `@param` and `@return` tags.

Author: eamonnmcmanus

functions-framework-api/src/main/java/com/google/cloud/functions/BackgroundFunction.java

@@ -23,11 +23,13 @@
  * <p>Here is an example of an implementation that accesses the {@code messageId} property from
  * a payload that matches a user-defined {@code PubSubMessage} class:
  *
+ * <!-- The {@code} placement is a bit strange here, to prevent spurious spaces introduced by the
+ *      javadoc tool. -->
  * <pre>
- * public class Example implements {@code BackgroundFunction<PubSubMessage>} {
+ * public class Example implements{@code BackgroundFunction<PubSubMessage>} {
  *   private static final Logger logger = Logger.getLogger(Example.class.getName());
  *
- *   {@code @Override}
+ *  {@code @Override}
  *   public void accept(PubSubMessage pubSubMessage, Context context) {
  *     logger.info("Got messageId " + pubSubMessage.messageId);
  *   }
@@ -36,7 +38,7 @@
  * // Where PubSubMessage is a user-defined class like this:
  * public class PubSubMessage {
  *   String data;
- *   {@code Map<String, String>} attributes;
+ *  {@code Map<String, String>} attributes;
  *   String messageId;
  *   String publishTime;
  * }
@@ -54,6 +56,7 @@ public interface BackgroundFunction<T> {
    * @param payload the payload of the event, deserialized from the original JSON string.
    * @param context the context of the event. This is a set of values that every event has,
    *     separately from the payload, such as timestamp and event type.
+   * @throws Exception to produce a 500 status code in the HTTP response.
    */
   void accept(T payload, Context context) throws Exception;
 }

functions-framework-api/src/main/java/com/google/cloud/functions/HttpFunction.java

@@ -23,6 +23,10 @@ public interface HttpFunction {
    * Called to service an incoming HTTP request. This interface is implemented by user code to
    * provide the action for a given function. If the method throws any exception (including any
    * {@link Error}) then the HTTP response will have a 500 status code.
+   *
+   * @param request a representation of the incoming HTTP request.
+   * @param response an object that can be used to provide the corresponding HTTP response.
+   * @throws Exception if thrown, the HTTP response will have a 500 status code.
    */
   void service(HttpRequest request, HttpResponse response) throws Exception;
 }

functions-framework-api/src/main/java/com/google/cloud/functions/HttpMessage.java

@@ -25,16 +25,26 @@
  * Represents an HTTP message, either an HTTP request or a part of a multipart HTTP request.
  */
 public interface HttpMessage {
-  /** Returns the value of the {@code Content-Type} header, if any. */
+  /**
+   * Returns the value of the {@code Content-Type} header, if any.
+   *
+   * @return the content type, if any.
+   */
   Optional<String> getContentType();
 
-  /** Returns the numeric value of the {@code Content-Length} header. */
+  /**
+   * Returns the numeric value of the {@code Content-Length} header.
+   *
+   * @return the content length.
+   */
   long getContentLength();
 
   /**
    * Returns the character encoding specified in the {@code Content-Type} header,
    * or {@code Optional.empty()} if there is no {@code Content-Type} header or it does not have the
    * {@code charset} parameter.
+   *
+   * @return the character encoding for the content type, if one is specified.
    */
   Optional<String> getCharacterEncoding();
 
@@ -44,6 +54,7 @@ public interface HttpMessage {
    * This method is typically used to read binary data. If the body is text, the
    * {@link #getReader()} method is more appropriate.
    *
+   * @return an {@link InputStream} that can be used to read the body of this HTTP request.
    * @throws IOException if a valid {@link InputStream} cannot be returned for some reason.
    * @throws IllegalStateException if {@link #getReader()} has already been called on this instance.
    */
@@ -53,6 +64,7 @@ public interface HttpMessage {
    * Returns a {@link BufferedReader} that can be used to read the text body of this HTTP request.
    * Every call to this method on the same {@link HttpMessage} will return the same object.
    *
+   * @return a {@link BufferedReader} that can be used to read the text body of this HTTP request.
    * @throws IOException if a valid {@link BufferedReader} cannot be returned for some reason.
    * @throws IllegalStateException if {@link #getInputStream()} has already been called on this
    *     instance.
@@ -69,9 +81,12 @@ public interface HttpMessage {
    *   Some-Header: another value
    * </pre>
    *
-   * ...then the returned value will map {@code Content-Type} to a one-element list containing
-   * {@code text/plain}, and {@code Some-Header} to a two-element list containing {@code some value}
-   * and {@code another value}.
+   * ...then the returned value will map {@code "Content-Type"} to a one-element list containing
+   * {@code "text/plain"}, and {@code "Some-Header"} to a two-element list containing
+   * {@code "some value"} and {@code "another value"}.
+   *
+   * @return a map where each key is an HTTP header and the corresponding {@code List} value has
+   *     one element for each occurrence of that header.
    */
   Map<String, List<String>> getHeaders();
 
@@ -87,6 +102,10 @@ public interface HttpMessage {
    *
    * ...then {@code getFirstHeader("Some-Header")} will return {@code Optional.of("some value")},
    * and {@code getFirstHeader("Another-Header")} will return {@code Optional.empty()}.
+   *
+   * @param name an HTTP header name.
+   *
+   * @return the first value of the given header, if present.
    */
   default Optional<String> getFirstHeader(String name) {
     List<String> headers = getHeaders().get(name);

functions-framework-api/src/main/java/com/google/cloud/functions/HttpRequest.java

@@ -22,30 +22,45 @@
  * Represents the contents of an HTTP request that is being serviced by a Cloud Function.
  */
 public interface HttpRequest extends HttpMessage {
-  /** The HTTP method of this request, such as {@code "POST"} or {@code "GET"}. */
+  /**
+   * The HTTP method of this request, such as {@code "POST"} or {@code "GET"}.
+   *
+   * @return the HTTP method of this request.
+   */
   String getMethod();
 
-  /** The full URI of this request as it arrived at the server. */
+  /**
+   * The full URI of this request as it arrived at the server.
+   *
+   * @return the full URI of this request.
+   */
   String getUri();
 
   /**
    * The path part of the URI for this request, without any query. If the full URI is
    * {@code http://foo.com/bar/baz?this=that}, then this method will return {@code /bar/baz}.
+   *
+   * @return the path part of the URI for this request.
    */
   String getPath();
 
   /**
    * The query part of the URI for this request. If the full URI is
    * {@code http://foo.com/bar/baz?this=that}, then this method will return {@code this=that}.
    * If there is no query part, the returned {@code Optional} is empty.
+   *
+   * @return the query part of the URI, if any.
    */
   Optional<String> getQuery();
 
   /**
    * The query parameters of this request. If the full URI is
    * {@code http://foo.com/bar?thing=thing1&thing=thing2&cat=hat}, then the returned map will map
-   * {@code thing} to the list {@code "thing1", "thing2"} and {@code cat} to the list with the
+   * {@code thing} to the list {@code ["thing1", "thing2"]} and {@code cat} to the list with the
    * single element {@code "hat"}.
+   *
+   * @return a map where each key is the name of a query parameter and the corresponding
+   *     {@code List} value indicates every value that was associated with that name.
    */
   Map<String, List<String>> getQueryParameters();
 
@@ -55,6 +70,9 @@ public interface HttpRequest extends HttpMessage {
    * {@code getFirstQueryParameter("thing")} will return {@code Optional.of("thing1")} and
    * {@code getFirstQueryParameter("something")} will return {@code Optional.empty()}. This is a
    * more convenient alternative to {@link #getQueryParameters}.
+   *
+   * @param name a query parameter name.
+   * @return the first query parameter value with the given name, if any.
    */
   default Optional<String> getFirstQueryParameter(String name) {
     List<String> parameters = getQueryParameters().get(name);
@@ -70,7 +88,11 @@ default Optional<String> getFirstQueryParameter(String name) {
    * {@link HttpMessage}.
    */
   interface HttpPart extends HttpMessage {
-    /** Returns the filename associated with this part, if any. */
+    /**
+     * Returns the filename associated with this part, if any.
+     *
+     * @return the filename associated with this part, if any.
+     */
     Optional<String> getFileName();
   }
 
@@ -79,6 +101,7 @@ interface HttpPart extends HttpMessage {
    * in the returned map has the name of the part as its key and the contents as the associated
    * value.
    *
+   * @return a map from part names to part contents.
    * @throws IllegalStateException if the {@link #getContentType() content type} is not
    *     {@code multipart/form-data}.
    */

functions-framework-api/src/main/java/com/google/cloud/functions/HttpResponse.java

@@ -29,42 +29,63 @@ public interface HttpResponse {
   /**
    * Sets the numeric HTTP
    * <a href="https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">status
-   * code</a> to use in the response. Most often this will be 200, which is the OK status.
+   * code</a> to use in the response. Most often this will be 200, which is the OK status. The
+   * named constants in {@link java.net.HttpURLConnection}, such as
+   * {@link java.net.HttpURLConnection#HTTP_OK HTTP_OK}, can be used as an alternative to writing
+   * numbers in your source code.
+   *
+   * @param code the status code.
    */
   void setStatusCode(int code);
 
   /**
    * Sets the numeric HTTP
    * <a href="https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml">status
    * code</a> and reason message to use in the response. For example<br>
-   * {@code setStatusCode(400, "Something went wrong")}.
+   * {@code setStatusCode(400, "Something went wrong")}. The
+   * named constants in {@link java.net.HttpURLConnection}, such as
+   * {@link java.net.HttpURLConnection#HTTP_BAD_REQUEST HTTP_BAD_REQUEST}, can be used as an
+   * alternative to writing numbers in your source code.
+   *
+   * @param code the status code.
+   * @param message the status message.
    */
   void setStatusCode(int code, String message);
 
   /**
    * Sets the value to use for the {@code Content-Type} header in the response. This may include
    * a character encoding, for example {@code setContentType("text/plain; charset=utf-8")}.
+   *
+   * @param contentType the content type.
    */
   void setContentType(String contentType);
 
   /**
    * Returns the {@code Content-Type} that was previously set by {@link #setContentType}, or by
    * {@link #appendHeader} with a header name of {@code Content-Type}. If no {@code Content-Type}
    * has been set, returns {@code Optional.empty()}.
+   *
+   * @return the content type, if any.
    */
   Optional<String> getContentType();
 
   /**
    * Includes the given header name with the given value in the response. This method may be called
    * several times for the same header, in which case the response will contain the header the same
    * number of times.
+   *
+   * @param header an HTTP header, such as {@code Content-Type}.
+   * @param value a value to associate with that header.
    */
   void appendHeader(String header, String value);
 
   /**
    * Returns the headers that have been defined for the response so far. This will contain at least
    * the headers that have been set via {@link #appendHeader} or {@link #setContentType}, and may
    * contain additional headers such as {@code Date}.
+   *
+   * @return a map where each key is a header name and the corresponding {@code List} value has one
+   *     entry for every value associated with that header.
    */
   Map<String, List<String>> getHeaders();
 
@@ -73,6 +94,7 @@ public interface HttpResponse {
    * This method is typically used to write binary data. If the body is text, the
    * {@link #getWriter()} method is more appropriate.
    *
+   * @return the output stream.
    * @throws IOException if a valid {@link OutputStream} cannot be returned for some reason.
    * @throws IllegalStateException if {@link #getWriter} has already been called on this instance.
    */
@@ -85,6 +107,7 @@ public interface HttpResponse {
    * {@link #appendHeader appendHeader("Content-Type", "text/foo; charset=bar")}
    * before calling this method.
    *
+   * @return the writer.
    * @throws IOException if a valid {@link BufferedWriter} cannot be returned for some reason.
    * @throws IllegalStateException if {@link #getOutputStream} has already been called on this
    *     instance.

functions-framework-api/src/main/java/com/google/cloud/functions/RawBackgroundFunction.java

@@ -22,11 +22,13 @@
  * <p>Here is an example of an implementation that parses the JSON payload using Gson, to access its
  * {@code messageId} property:
  *
+ * <!-- The {@code} placement is a bit strange here, to prevent spurious spaces introduced by the
+ *      javadoc tool. -->
  * <pre>
  * public class Example implements RawBackgroundFunction {
  *   private static final Logger logger = Logger.getLogger(Example.class.getName());
  *
- *   {@code @Override}
+ *  {@code @Override}
  *   public void accept(String json, Context context) {
  *     JsonObject jsonObject = new Gson().fromJson(json, JsonObject.class);
  *     JsonElement messageId = jsonObject.get("messageId");
@@ -43,7 +45,7 @@
  * public class Example implements RawBackgroundFunction {
  *   private static final Logger logger = Logger.getLogger(Example.class.getName());
  *
- *   {@code @Override}
+ *  {@code @Override}
  *   public void accept(String json, Context context) {
  *     PubSubMessage message = new Gson().fromJson(json, PubSubMessage.class);
  *     logger.info("Got messageId " + message.messageId);
@@ -53,7 +55,7 @@
  * // Where PubSubMessage is a user-defined class like this:
  * public class PubSubMessage {
  *   String data;
- *   {@code Map<String, String>} attributes;
+ *  {@code Map<String, String>} attributes;
  *   String messageId;
  *   String publishTime;
  * }
@@ -69,6 +71,7 @@ public interface RawBackgroundFunction {
    * @param json the payload of the event, as a JSON string.
    * @param context the context of the event. This is a set of values that every event has,
    *     separately from the payload, such as timestamp and event type.
+   * @throws Exception to produce a 500 status code in the HTTP response.
    */
   void accept(String json, Context context) throws Exception;
 }