Merge pull request #729 from stripe/ob-javadoc

Add missing Javadoc

Author: ob-stripe

src/main/java/com/stripe/model/EphemeralKey.java

@@ -1,5 +1,7 @@
 package com.stripe.model;
 
+import com.google.gson.annotations.SerializedName;
+
 import com.stripe.exception.StripeException;
 import com.stripe.net.ApiResource;
 import com.stripe.net.RequestOptions;
@@ -15,18 +17,40 @@
 @Setter
 @EqualsAndHashCode(callSuper = false)
 public class EphemeralKey extends ApiResource implements HasId {
-  @Getter(onMethod = @__({@Override})) String id;
-  String object;
+  /** Time at which the object was created. Measured in seconds since the Unix epoch. */
+  @SerializedName("created")
   Long created;
+
+  /** Time at which the key will expire. Measured in seconds since the Unix epoch. */
+  @SerializedName("expires")
   Long expires;
+
+  /** Unique identifier for the object. */
+  @Getter(onMethod = @__({@Override}))
+  @SerializedName("id")
+  String id;
+
+  /**
+   * Has the value {@code true} if the object exists in live mode or the value {@code false} if
+   * the object exists in test mode.
+   */
+  @SerializedName("livemode")
   Boolean livemode;
+
+  /** String representing the object's type. Objects of the same type share the same value. */
+  @SerializedName("object")
+  String object;
+
+  /** The key's secret. You can use this value to make authorized requests to the Stripe API. */
+  @SerializedName("secret")
   String secret;
+
   List<AssociatedObject> associatedObjects;
+
   transient String rawJson;
 
-  // <editor-fold desc="create">
   /**
-   * Creates an ephemeral key.
+   * Creates an ephemeral API key for a given resource.
    *
    * @param params request parameters
    * @param options request options. {@code stripeVersion} is required when creating ephemeral
@@ -43,24 +67,21 @@ public static EphemeralKey create(Map<String, Object> params, RequestOptions opt
     return request(RequestMethod.POST, classUrl(EphemeralKey.class), params, EphemeralKey.class,
         options);
   }
-  // </editor-fold>
 
-  // <editor-fold desc="delete">
   /**
-   * Delete an ephemeral key.
+   * Invalidates an ephemeral API key for a given resource.
    */
   public EphemeralKey delete() throws StripeException {
     return delete(null);
   }
 
   /**
-   * Delete an ephemeral key.
+   * Invalidates an ephemeral API key for a given resource.
    */
   public EphemeralKey delete(RequestOptions options) throws StripeException {
     return request(RequestMethod.DELETE, instanceUrl(EphemeralKey.class, this.id),
         (Map<String,Object>) null, EphemeralKey.class, options);
   }
-  // </editor-fold>
 
   @Getter
   @Setter

src/main/java/com/stripe/model/Event.java

@@ -1,5 +1,7 @@
 package com.stripe.model;
 
+import com.google.gson.annotations.SerializedName;
+
 import com.stripe.exception.StripeException;
 import com.stripe.net.ApiResource;
 import com.stripe.net.RequestOptions;
@@ -14,15 +16,56 @@
 @Setter
 @EqualsAndHashCode(callSuper = false)
 public class Event extends ApiResource implements HasId {
-  @Getter(onMethod = @__({@Override})) String id;
-  String object;
+  /** For Connect webhook events, the identifier of the account that emitted the event. */
+  @SerializedName("account")
   String account;
+
+  /**
+   * The Stripe API version used to render {@code data}. <i>Note: This property is populated only
+   * for events on or after October 31, 2014.</i>
+   */
+  @SerializedName("api_version")
   String apiVersion;
+
+  /** Time at which the object was created. Measured in seconds since the Unix epoch. */
+  @SerializedName("created")
   Long created;
+
+  /** Object containing data associated with the event. */
+  @SerializedName("data")
   EventData data;
+
+  /** Unique identifier for the object. */
+  @Getter(onMethod = @__({@Override}))
+  @SerializedName("id")
+  String id;
+
+  /**
+   * Has the value {@code true} if the object exists in live mode or the value {@code false} if
+   * the object exists in test mode.
+   */
+  @SerializedName("livemode")
   Boolean livemode;
+
+  /** String representing the object's type. Objects of the same type share the same value. */
+  @SerializedName("object")
+  String object;
+
+  /**
+   * Number of webhooks that have yet to be successfully delivered (i.e., to return a 20x
+   * response) to the URLs you’ve specified.
+   */
+  @SerializedName("pending_webhooks")
   Long pendingWebhooks;
+
+  /** Information on the API request that instigated the event. */
+  @SerializedName("request")
   EventRequest request;
+
+  /**
+   * Description of the event (e.g., {@code invoice.created} or {@code charge.refunded}).
+   */
+  @SerializedName("type")
   String type;
 
   /**
@@ -51,44 +94,49 @@ public EventDataObjectDeserializer getDataObjectDeserializer() {
     return new EventDataObjectDeserializer(apiVersion, type, data.object);
   }
 
-  // <editor-fold desc="list">
   /**
-   * List all events.
+   * List events, going back up to 30 days. Each event data is rendered according to Stripe API
+   * version at its creation time, specified in
+   * <a href="https://stripe.com/docs/api/events/object">event object</a> {@code api_version}
+   * attribute (not according to your current Stripe API version or {@code Stripe-Version} header).
    */
   public static EventCollection list(Map<String, Object> params) throws StripeException {
     return list(params, null);
   }
 
   /**
-   * List all events.
+   * List events, going back up to 30 days. Each event data is rendered according to Stripe API
+   * version at its creation time, specified in
+   * <a href="https://stripe.com/docs/api/events/object">event object</a> {@code api_version}
+   * attribute (not according to your current Stripe API version or {@code Stripe-Version} header).
    */
   public static EventCollection list(Map<String, Object> params, RequestOptions options)
       throws StripeException {
     return requestCollection(classUrl(Event.class), params, EventCollection.class, options);
   }
-  // </editor-fold>
 
-  // <editor-fold desc="retrieve">
   /**
-   * Retrieve an event.
+   * Retrieves the details of an event. Supply the unique identifier of the event, which you might
+   * have received in a webhook.
    */
   public static Event retrieve(String id) throws StripeException {
     return retrieve(id, (RequestOptions) null);
   }
 
   /**
-   * Retrieve an event.
+   * Retrieves the details of an event. Supply the unique identifier of the event, which you might
+   * have received in a webhook.
    */
   public static Event retrieve(String id, RequestOptions options) throws StripeException {
     return retrieve(id, null, options);
   }
 
   /**
-   * Retrieve an event.
+   * Retrieves the details of an event. Supply the unique identifier of the event, which you might
+   * have received in a webhook.
    */
   public static Event retrieve(String id, Map<String, Object> params, RequestOptions options)
       throws StripeException {
     return request(RequestMethod.GET, instanceUrl(Event.class, id), params, Event.class, options);
   }
-  // </editor-fold>
 }

src/main/java/com/stripe/model/EventData.java

@@ -2,6 +2,7 @@
 
 import com.google.gson.JsonObject;
 import com.google.gson.JsonParseException;
+import com.google.gson.annotations.SerializedName;
 import java.util.Map;
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
@@ -15,6 +16,7 @@ public class EventData extends StripeObject {
    * Raw JSON object intended to be deserialized as {@code StripeObject}. The deserialization
    * should be deferred to the user. See the now deprecated method {@link EventData#getObject()}.
    */
+  @SerializedName("object")
   JsonObject object;
 
   /**
@@ -23,6 +25,7 @@ public class EventData extends StripeObject {
    * {@code Map<String, Object>}, {@code List<Object>}, and basic Java data types.
    * The array was previously represented as {@code Object[]} in `stripe-java` below v9.x
    */
+  @SerializedName("previous_attributes")
   Map<String, Object> previousAttributes;
 
   /**
@@ -36,4 +39,4 @@ public class EventData extends StripeObject {
   public StripeObject getObject() {
     return EventDataDeserializer.deserializeStripeObject(object);
   }
-}
+}

src/main/java/com/stripe/model/EventRequest.java

@@ -1,5 +1,7 @@
 package com.stripe.model;
 
+import com.google.gson.annotations.SerializedName;
+
 import lombok.EqualsAndHashCode;
 import lombok.Getter;
 import lombok.Setter;
@@ -8,6 +10,14 @@
 @Setter
 @EqualsAndHashCode(callSuper = false)
 public class EventRequest extends StripeObject {
+  /** ID of the API request that caused the event. If null, the event was automatic (e.g., Stripe’s
+   * automatic subscription handling). Request logs are available in the
+   * <a href="https://dashboard.stripe.com/logs">dashboard</a>, but currently not in the API. */
+  @SerializedName("id")
   String id;
+
+  /** The idempotency key transmitted during the request, if any. <i>Note: This property is
+   * populated only for events on or after May 23, 2017.</i> */
+  @SerializedName("idempotency_key")
   String idempotencyKey;
 }

src/main/java/com/stripe/model/File.java

@@ -1,5 +1,7 @@
 package com.stripe.model;
 
+import com.google.gson.annotations.SerializedName;
+
 import com.stripe.Stripe;
 import com.stripe.exception.StripeException;
 import com.stripe.net.ApiResource;
@@ -15,73 +17,113 @@
 @Setter
 @EqualsAndHashCode(callSuper = false)
 public class File extends ApiResource implements HasId {
-  @Getter(onMethod = @__({@Override})) String id;
-  String object;
+  /** Time at which the object was created. Measured in seconds since the Unix epoch. */
+  @SerializedName("created")
   Long created;
+
+  /** A filename for the file, suitable for saving to a filesystem. */
+  @SerializedName("filename")
   String filename;
+
+  /** Unique identifier for the object. */
+  @Getter(onMethod = @__({@Override}))
+  @SerializedName("id")
+  String id;
+
+  @SerializedName("links")
   FileLinkCollection links;
+
+  /** String representing the object's type. Objects of the same type share the same value. */
+  @SerializedName("object")
+  String object;
+
+  /**
+   * The purpose of the file. Possible values are {@code business_icon}, {@code business_logo},
+   * {@code customer_signature}, {@code dispute_evidence}, {@code finance_report_run},
+   * {@code identity_document}, {@code pci_document}, {@code sigma_scheduled_query}, or
+   * {@code tax_document_user_upload}.
+   */
+  @SerializedName("purpose")
   String purpose;
+
+  /** The size in bytes of the file object. */
+  @SerializedName("size")
   Long size;
+
+  /** A user friendly title for the document. */
+  @SerializedName("title")
   String title;
+
+  /**
+   * The type of the file returned (e.g., {@code csv}, {@code pdf}, {@code jpg}, or
+   * {@code png}).
+   */
+  @SerializedName("type")
   String type;
+
+  /** The URL from which the file can be downloaded using your live secret API key. */
+  @SerializedName("url")
   String url;
 
-  // <editor-fold desc="create">
   /**
-   * Create a file.
+   * To upload a file to Stripe, you’ll need to send a request of type {@code multipart/form-data}.
+   * The request should contain the file you would like to upload, as well as the parameters for
+   * creating a file.
    */
   public static File create(Map<String, Object> params) throws StripeException {
     return create(params, (RequestOptions) null);
   }
 
   /**
-   * Create a file.
+   * To upload a file to Stripe, you’ll need to send a request of type {@code multipart/form-data}.
+   * The request should contain the file you would like to upload, as well as the parameters for
+   * creating a file.
    */
   public static File create(Map<String, Object> params, RequestOptions options)
       throws StripeException {
     return multipartRequest(RequestMethod.POST, classUrl(File.class, Stripe.getUploadBase()),
         params, File.class, options);
   }
-  // </editor-fold>
 
-  // <editor-fold desc="list">
   /**
-   * List all files.
+   * Returns a list of the files that your account has access to. The files are returned sorted by
+   * creation date, with the most recently created files appearing first.
    */
   public static FileCollection list(Map<String, Object> params) throws StripeException {
     return list(params, null);
   }
 
   /**
-   * List all files.
+   * Returns a list of the files that your account has access to. The files are returned sorted by
+   * creation date, with the most recently created files appearing first.
    */
   public static FileCollection list(Map<String, Object> params, RequestOptions options)
       throws StripeException {
     return requestCollection(classUrl(File.class), params, FileCollection.class, options);
   }
-  // </editor-fold>
 
-  // <editor-fold desc="retrieve">
   /**
-   * Retrieve a file.
+   * Retrieves the details of an existing file object. Supply the unique file ID from a file, and
+   * Stripe will return the corresponding file object.
    */
   public static File retrieve(String id) throws StripeException {
     return retrieve(id, (RequestOptions) null);
   }
 
   /**
-   * Retrieve a file.
+   * Retrieves the details of an existing file object. Supply the unique file ID from a file, and
+   * Stripe will return the corresponding file object.
    */
   public static File retrieve(String id, RequestOptions options) throws StripeException {
     return retrieve(id, null, options);
   }
 
   /**
-   * Retrieve a file.
+   * Retrieves the details of an existing file object. Supply the unique file ID from a file, and
+   * Stripe will return the corresponding file object.
    */
   public static File retrieve(String id, Map<String, Object> params, RequestOptions options)
       throws StripeException {
     return request(RequestMethod.GET, instanceUrl(File.class, id), params, File.class, options);
   }
-  // </editor-fold>
 }