Overhaul javadocs, using Oracle's styleguide

See http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide

src/main/java/com/sendgrid/ASM.java

@@ -7,7 +7,8 @@
 import java.util.Arrays;
 
 /**
- * An object allowing you to specify how to handle unsubscribes.
+ * A JSON-serializable model, describing how unsubscribes should
+ * be handled.
  */
 @JsonInclude(Include.NON_DEFAULT)
 public class ASM {
@@ -19,7 +20,8 @@ public class ASM {
     private int[] groupsToDisplay;
 
     /**
-     * Get the group ID.
+     * Gets the group ID.
+     *
      * @return the group ID.
      */
     @JsonProperty("group_id")
@@ -28,17 +30,19 @@ public int getGroupId() {
     }
 
     /**
-     * Set the group ID.
+     * Sets the group ID.
+     *
      * @param groupId the group ID.
-     * @return this object.
+     * @return {@code this} for chaining.
      */
     public ASM groupId(int groupId) {
         this.groupId = groupId;
         return this;
     }
 
     /**
-     * Get the groups to display.
+     * Gets the groups to display.
+     *
      * @return the groups to display.
      */
     @JsonProperty("groups_to_display")
@@ -47,9 +51,10 @@ public int[] getGroupsToDisplay() {
     }
 
     /**
-     * Set the groups to display.
+     * Sets the groups to display.
+     *
      * @param groupsToDisplay the groups to display.
-     * @return this object.
+     * @return {@code this} for chaining.
      */
     public ASM groupsToDisplay(int[] groupsToDisplay) {
         this.groupsToDisplay = Arrays.copyOf(groupsToDisplay, groupsToDisplay.length);

src/main/java/com/sendgrid/Attachment.java

@@ -9,7 +9,7 @@
 import java.io.*;
 
 /**
- * An attachment object.
+ * A JSON-serializable model of an email attachment.
  */
 @JsonInclude(Include.NON_DEFAULT)
 public class Attachment {
@@ -28,15 +28,16 @@ public class Attachment {
 
     /** 
      * The attachment content ID. This is used when the 
-     * disposition is set to “inline” and the attachment 
+     * disposition is set to {@code "inline"} and the attachment
      * is an image, allowing the file to be displayed within 
-     * the body of your email. 
+     * the body of your email.
      */
     @JsonProperty("content_id")
     private String contentId;
 
     /**
-     * Get the attachment's content.
+     * Gets the attachment content.
+     *
      * @return the content.
      */
     @JsonProperty("content")
@@ -45,18 +46,20 @@ public String getContent() {
     }
 
     /**
-     * Set the attachment's content.
+     * Sets the attachment content.
+     *
      * @param content the content.
-     * @return this object.
+     * @return {@code this} for chaining.
      */
     public Attachment content(String content) {
         this.content = content;
         return this;
     }
 
     /**
-     * Get the mime type of the content you are attaching. For example, 
-     * “text/plain” or “text/html”.
+     * Gets the mime type of the content you are attaching. For example,
+     * {@link ContentType#TEXT_PLAIN} or {@link ContentType#TEXT_HTML}.
+     *
      * @return the mime type.
      */
     @JsonProperty("type")
@@ -65,17 +68,19 @@ public String getType() {
     }
 
     /**
-     * Set the mime type of the content.
+     * Sets the mime type of the content.
+     *
      * @param type the mime type.
-     * @return this object.
+     * @return {@code this} for chaining.
      */
     public Attachment type(String type) {
         this.type = type;
         return this;
     }
 
     /**
-     * Get the filename for this attachment.
+     * Gets the filename for this attachment.
+     *
      * @return the file name.
      */
     @JsonProperty("filename")
@@ -84,23 +89,25 @@ public String getFilename() {
     }
 
     /**
-     * Set the filename for this attachment.
+     * Sets the filename for this attachment.
+     *
      * @param filename the filename.
-     * @return this object.
+     * @return {@code this} for chaining.
      */
     public Attachment filename(String filename) {
         this.filename = filename;
         return this;
     }
 
     /**
-     * Get the content-disposition of the attachment specifying 
+     * Gets the content-disposition of the attachment specifying
      * how you would like the attachment to be displayed. 
-     * For example, “inline” results in the attached file 
+     * For example, {@code "inline"} results in the attached file
      * being displayed automatically within the message 
-     * while “attachment” results in the attached file 
+     * while {@code “attachment”} results in the attached file
      * requiring some action to be taken before it is 
      * displayed (e.g. opening or downloading the file).
+     *
      * @return the disposition.
      */
     @JsonProperty("disposition")
@@ -109,20 +116,22 @@ public String getDisposition() {
     }
 
     /**
-     * Set the content-disposition of the attachment.
+     * Sets the content-disposition of the attachment.
+     *
      * @param disposition the disposition.
-     * @return this object.
+     * @return {@code this} for chaining.
      */
     public Attachment disposition(String disposition) {
         this.disposition = disposition;
         return this;
     }
 
     /**
-     * Get the attachment content ID. This is used when the 
-     * disposition is set to “inline” and the attachment 
+     * Gets the attachment content ID. This is used when the
+     * disposition is set to {@code "inline"} and the attachment
      * is an image, allowing the file to be displayed within 
-     * the body of your email. 
+     * the body of your email.
+     *
      * @return the content ID.
      */
     @JsonProperty("content_id")
@@ -131,17 +140,18 @@ public String getContentId() {
     }
 
     /**
-     * Set the content ID.
+     * Sets the content ID.
+     *
      * @param contentId the content ID.
-     * @return this object.
+     * @return {@code this} for chaining.
      */
     public Attachment contentId(String contentId) {
         this.contentId = contentId;
         return this;
     }
 
     /**
-     * A helper object to construct usable attachment.
+     * A builder for creating {@link Attachment}s.
      */
     @JsonIgnoreType
     public static class Builder {
@@ -155,7 +165,8 @@ public static class Builder {
         private String contentId;
 
         /**
-         * Construct a new attachment builder.
+         * Creates a new builder, for creating an {@link Attachment}.
+         *
          * @param fileName the filename to include.
          * @param content an input stream for the content.
          * @throws IllegalArgumentException in case either the fileName or the content is null.
@@ -174,7 +185,8 @@ public Builder(String fileName, InputStream content) {
         }
 
         /**
-         * Construct a new attachment builder.
+         * Creates a new builder, for creating an {@link Attachment}.
+         *
          * @param fileName the filename to include.
          * @param content an input string for the content.
          * @throws IllegalArgumentException in case either the fileName or the content is null.
@@ -207,34 +219,42 @@ private String encodeToBase64(InputStream content) {
         }
 
         /**
-         * Set the type of this attachment builder.
+         * Sets the type of this attachment builder.
+         *
          * @param type the attachment type.
+         * @return {@code this} for chaining.
          */
         public Builder withType(String type) {
             this.type = type;
             return this;
         }
 
         /**
-         * Set the disposition of this attachment builder.
+         * Sets the disposition of this attachment builder.
+         *
          * @param disposition the disposition.
+         * @return {@code this} for chaining.
          */
         public Builder withDisposition(String disposition) {
             this.disposition = disposition;
             return this;
         }
 
         /**
-         * Set the content ID of this attachment builder.
+         * Sets the content ID of this attachment builder.
+         *
          * @param contentId the content ID.
+         * @return {@code this} for chaining.
          */
         public Builder withContentId(String contentId) {
             this.contentId = contentId;
             return this;
         }
 
         /**
-         * Construct the attachment object.
+         * Creates the attachment model, from the specified arguments.
+         *
+         * @return the constructed attachment model.
          */
         public Attachment build() {
             Attachment attachment = new Attachment()

src/main/java/com/sendgrid/BCCSettings.java

@@ -5,9 +5,9 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 
 /**
- * This object allows you to have a blind carbon copy 
- * automatically sent to the specified email address 
- * for every email that is sent.
+ * A JSON-serializable model of the blind carbon copy (BCC)
+ * settings. This allows for automatic copies of every
+ * email sent to be made to the specified email address.
  */
 @JsonInclude(Include.NON_DEFAULT)
 public class BCCSettings {
@@ -19,37 +19,43 @@ public class BCCSettings {
     private String email;
 
     /**
-     * Determines if this setting is enabled.
-     * @return true if BCC is enabled, false otherwise.
+     * Gets whether BCC has been enabled.
+     *
+     * @return {@code true} if BCC has been enabled;
+     *         {@code false} otherwise.
      */
     @JsonProperty("enable")
     public boolean getEnable() {
         return enable;
     }
 
     /**
-     * Set whether or not BCC is enabled.
-     * @param enable true if BCC is enabled, false otherwise.
-     * @return this object.
+     * Sets whether BCC has been enabled.
+     *
+     * @param enable {@code true} if BCC has been enabled;
+     *               {@code false} otherwise.
+     * @return {@code this} for chaining.
      */
     public BCCSettings enable(boolean enable) {
         this.enable = enable;
         return this;
     }
 
     /**
-     * Get the email address that you would like to receive the BCC.
-     * @return the address.
+     * Gets the email address that will receive the copies.
+     *
+     * @return the email address.
      */
     @JsonProperty("email")
     public String getEmail() {
         return this.email;
     }
 
     /**
-     * Set the email address that you would like to receive the BCC.
-     * @param email the address.
-     * @return this object.
+     * Sets the email address that will receive the copies.
+     *
+     * @param email the email address.
+     * @return {@code this} for chaining.
      */
     public BCCSettings email(String email) {
         this.email = email;