Add more API documentation

Author: delatbabel

src/Message/AuthorizeRequest.php

@@ -8,6 +8,11 @@
 /**
  * Stripe Authorize Request
  *
+ * An Authorize request is similar to a purchase request but the
+ * charge issues an authorization (or pre-authorization), and no money
+ * is transferred.  The transaction will need to be captured later
+ * in order to effect payment. Uncaptured charges expire in 7 days.
+ *
  * Example:
  *
  * <code>

src/Message/CaptureRequest.php

@@ -8,7 +8,6 @@
 /**
  * Stripe Capture Request
  *
- *
  * Use this request to capture and process a previously created authorization.
  *
  * Example -- note this example assumes that the authorization has been successful

src/Message/CreateCardRequest.php

@@ -1,9 +1,18 @@
 <?php
+/**
+ * Stripe Create Credit Card Request
+ */
 
 namespace Omnipay\Stripe\Message;
 
 /**
  * Stripe Create Credit Card Request
+ *
+ * This doesn't actually create a card, it creates a customer.
+ *
+ * See issue #8
+ *
+ * @link https://github.com/thephpleague/omnipay-stripe/issues/8
  */
 class CreateCardRequest extends AbstractRequest
 {

src/Message/DeleteCardRequest.php

@@ -1,9 +1,17 @@
 <?php
+/**
+ * Stripe Delete Credit Card Request
+ */
 
 namespace Omnipay\Stripe\Message;
 
 /**
  * Stripe Delete Credit Card Request
+ *
+ * This needs further work and/or explanation because it requires
+ * a customer ID.
+ *
+ * @link https://stripe.com/docs/api#delete_card
  */
 class DeleteCardRequest extends AbstractRequest
 {

src/Message/FetchTokenRequest.php

@@ -1,9 +1,14 @@
 <?php
+/**
+ * Stripe Fetch Token Request
+ */
 
 namespace Omnipay\Stripe\Message;
 
 /**
  * Stripe Fetch Token Request
+ *
+ * @link https://stripe.com/docs/api#tokens
  */
 class FetchTokenRequest extends AbstractRequest
 {

src/Message/FetchTransactionRequest.php

@@ -1,9 +1,29 @@
 <?php
+/**
+ * Stripe Fetch Transaction Request
+ */
 
 namespace Omnipay\Stripe\Message;
 
 /**
  * Stripe Fetch Transaction Request
+ *
+ * Example -- note this example assumes that the purchase has been successful
+ * and that the transaction ID returned from the purchase is held in $sale_id.
+ * See PurchaseRequest for the first part of this example transaction:
+ *
+ * <code>
+ *   // Fetch the transaction so that details can be found for refund, etc.
+ *   $transaction = $gateway->fetchTransaction();
+ *   $transaction->setTransactionReference($sale_id);
+ *   $response = $transaction->send();
+ *   $data = $response->getData();
+ *   echo "Gateway fetchTransaction response data == " . print_r($data, true) . "\n";
+ * </code>
+ *
+ * @see PurchaseRequest
+ * @see Omnipay\Stripe\Gateway
+ * @link https://stripe.com/docs/api#retrieve_charge
  */
 class FetchTransactionRequest extends AbstractRequest
 {

src/Message/RefundRequest.php

@@ -1,9 +1,52 @@
 <?php
+/**
+ * Stripe Refund Request
+ */
 
 namespace Omnipay\Stripe\Message;
 
 /**
  * Stripe Refund Request
+ *
+ * When you create a new refund, you must specify a
+ * charge to create it on.
+ *
+ * Creating a new refund will refund a charge that has
+ * previously been created but not yet refunded. Funds will
+ * be refunded to the credit or debit card that was originally
+ * charged. The fees you were originally charged are also
+ * refunded.
+ *
+ * You can optionally refund only part of a charge. You can
+ * do so as many times as you wish until the entire charge
+ * has been refunded.
+ *
+ * Once entirely refunded, a charge can't be refunded again.
+ * This method will return an error when called on an
+ * already-refunded charge, or when trying to refund more
+ * money than is left on a charge. 
+ *
+ * Example -- note this example assumes that the purchase has been successful
+ * and that the transaction ID returned from the purchase is held in $sale_id.
+ * See PurchaseRequest for the first part of this example transaction:
+ *
+ * <code>
+ *   // Do a refund transaction on the gateway
+ *   $transaction = $gateway->refund(array(
+ *       'amount'                   => '10.00',
+ *       'transactionReference'     => $sale_id,
+ *   ));
+ *   $response = $transaction->send();
+ *   if ($response->isSuccessful()) {
+ *       echo "Refund transaction was successful!\n";
+ *       $refund_id = $response->getTransactionReference();
+ *       echo "Transaction reference = " . $refund_id . "\n";
+ *   }
+ * </code>
+ *
+ * @see PurchaseRequest
+ * @see Omnipay\Stripe\Gateway
+ * @link https://stripe.com/docs/api#create_refund
  */
 class RefundRequest extends AbstractRequest
 {

src/Message/Response.php

@@ -1,15 +1,24 @@
 <?php
+/**
+ * Stripe Response
+ */
 
 namespace Omnipay\Stripe\Message;
 
 use Omnipay\Common\Message\AbstractResponse;
 
 /**
  * Stripe Response
+ *
+ * This is the response class for all Stripe requests.
+ *
+ * @see \Omnipay\Stripe\Gateway
  */
 class Response extends AbstractResponse
 {
     /**
+     * Is the transaction successful?
+     *
      * @return bool
      */
     public function isSuccessful()
@@ -18,6 +27,8 @@ public function isSuccessful()
     }
 
     /**
+     * Get the transaction reference.
+     *
      * @return string|null
      */
     public function getTransactionReference()
@@ -30,6 +41,8 @@ public function getTransactionReference()
     }
 
     /**
+     * Get a card reference, for createCard or createCustomer requests.
+     *
      * @return string|null
      */
     public function getCardReference()
@@ -42,6 +55,8 @@ public function getCardReference()
     }
 
     /**
+     * Get a token, for createCard requests.
+     *
      * @return string|null
      */
     public function getToken()
@@ -54,6 +69,8 @@ public function getToken()
     }
 
     /**
+     * Get the card data from the response.
+     *
      * @return array|null
      */
     public function getCard()
@@ -66,6 +83,10 @@ public function getCard()
     }
 
     /**
+     * Get the error message from the response.
+     *
+     * Returns null if the request was successful.
+     *
      * @return string|null
      */
     public function getMessage()