Adding documentation, adding documentation generation script

.gitignore

@@ -2,3 +2,6 @@
 composer.lock
 composer.phar
 phpunit.xml
+.directory
+reports/
+documents/

makedoc.sh

@@ -0,0 +1,23 @@
+#!/bin/sh
+
+mkdir -p ./reports
+mkdir -p ./documents/apigen
+
+if [ -z "$1" ]; then
+    apigen \
+    --title 'Onmipay Common API documentation' \
+    --source ./src \
+    --destination ./documents/apigen \
+    --report ./reports/apigen.xml
+
+#
+# Left here for further expansion, ignore this for the time being.
+#
+elif [ "$1" = "common" ]; then
+    apigen \
+    --title 'Omnipay Common API documentation' \
+    --source ./src/Omnipay/Common \
+    --destination ./documents/apigen \
+    --report ./reports/apigen.xml
+
+fi

src/Omnipay/Common/AbstractGateway.php

@@ -1,4 +1,7 @@
 <?php
+/**
+ * Base payment gateway class
+ */
 
 namespace Omnipay\Common;
 
@@ -9,6 +12,11 @@
 
 /**
  * Base payment gateway class
+ *
+ * This abstract class should be extended by all payment gateways
+ * throughout the Omnipay system.  It enforces implementation of
+ * the GatewayInterface interface and defines various common attibutes
+ * and methods that all gateways should have.
  */
 abstract class AbstractGateway implements GatewayInterface
 {

src/Omnipay/Common/CreditCard.php

@@ -1,4 +1,7 @@
 <?php
+/**
+ * Credit Card class
+ */
 
 namespace Omnipay\Common;
 
@@ -9,6 +12,9 @@
 
 /**
  * Credit Card class
+ *
+ * This class defines and abstracts all of the credit card types used
+ * throughout the Omnipay system.
  */
 class CreditCard
 {

src/Omnipay/Common/Currency.php

@@ -1,9 +1,16 @@
 <?php
+/**
+ * Currency class
+ */
 
 namespace Omnipay\Common;
 
 /**
  * Currency class
+ *
+ * This class abstracts certain functionality around currency objects,
+ * currency codes and currency numbers relating to global currencies used
+ * in the Omnipay system.
  */
 class Currency
 {

src/Omnipay/Common/GatewayFactory.php

@@ -1,13 +1,27 @@
 <?php
+/**
+ * Omnipay Gateway Factory class
+ */
 
 namespace Omnipay\Common;
 
 use Guzzle\Http\ClientInterface;
 use Omnipay\Common\Exception\RuntimeException;
 use Symfony\Component\HttpFoundation\Request as HttpRequest;
 
+/**
+ * Omnipay Gateway Factory class
+ *
+ * This class abstracts a set of gateways that can be independently
+ * registered, accessed, and used.
+ */
 class GatewayFactory
 {
+    /**
+     * Internal storage for all available gateways
+     *
+     * @var array
+     */
     private $gateways = array();
 
     /**

src/Omnipay/Common/GatewayInterface.php

@@ -1,9 +1,15 @@
 <?php
+/**
+ * Payment gateway interface
+ */
 
 namespace Omnipay\Common;
 
 /**
  * Payment gateway interface
+ *
+ * This interface class defines the standard functions that any
+ * Omnipay gateway needs to define.
  */
 interface GatewayInterface
 {

src/Omnipay/Common/Helper.php

@@ -1,14 +1,23 @@
 <?php
+/**
+ * Helper class
+ */
 
 namespace Omnipay\Common;
 
 /**
  * Helper class
+ *
+ * This class defines various static utility functions that are in use
+ * throughout the Omnipay system. 
  */
 class Helper
 {
     /**
      * Convert a string to camelCase. Strings already in camelCase will not be harmed.
+     *
+     * @param  string  $str The input string
+     * @return string camelCased output string
      */
     public static function camelCase($str)
     {
@@ -88,6 +97,9 @@ public static function getGatewayShortName($className)
      *      Stripe              => \Omnipay\Stripe\Gateway
      *      PayPal\Express      => \Omnipay\PayPal\ExpressGateway
      *      PayPal_Express      => \Omnipay\PayPal\ExpressGateway
+     *
+     * @param  string  $shortName The short gateway name
+     * @return string  The fully namespaced gateway class name
      */
     public static function getGatewayClassName($shortName)
     {

src/Omnipay/Common/Issuer.php

@@ -1,19 +1,46 @@
 <?php
+/**
+ * Issuer
+ */
 
 namespace Omnipay\Common;
 
 /**
  * Issuer
+ *
+ * This class abstracts some functionality around card issuers used in the
+ * Omnipay system.
  */
 class Issuer
 {
+    /**
+     * The identifier of the issuer.
+     *
+     * @var string
+     */
     protected $id;
+
+    /**
+     * The full name of the issuer.
+     *
+     * @var string
+     */
     protected $name;
+
+    /**
+     * The ID of a payment method that the issuer belongs to.
+     *
+     * @see PaymentMethod
+     *
+     * @var string
+     */
     protected $paymentMethod;
 
     /**
      * Create a new Issuer
      *
+     * @see PaymentMethod
+     *
      * @param string      $id            The identifier of this issuer
      * @param string      $name          The name of this issuer
      * @param string|null $paymentMethod The ID of a payment method this issuer belongs to
@@ -48,6 +75,8 @@ public function getName()
     /**
      * The ID of a payment method this issuer belongs to
      *
+     * @see PaymentMethod
+     *
      * @return string
      */
     public function getPaymentMethod()

src/Omnipay/Common/Item.php

@@ -1,11 +1,18 @@
 <?php
+/**
+ * Cart Item
+ */
 
 namespace Omnipay\Common;
 
 use Symfony\Component\HttpFoundation\ParameterBag;
 
 /**
  * Cart Item
+ *
+ * This class defines a single cart item in the Omnipay system.
+ *
+ * @see ItemInterface
  */
 class Item implements ItemInterface
 {

src/Omnipay/Common/ItemBag.php

@@ -1,12 +1,25 @@
 <?php
+/**
+ * Cart Item Bag
+ */
 
 namespace Omnipay\Common;
 
+/**
+ * Cart Item Bag
+ *
+ * This class defines a bag (multi element set or array) of single cart items
+ * in the Omnipay system.
+ *
+ * @see Item
+ */
 class ItemBag implements \IteratorAggregate, \Countable
 {
     /**
      * Item storage
      *
+     * @see Item
+     *
      * @var array
      */
     protected $items;
@@ -24,6 +37,8 @@ public function __construct(array $items = array())
     /**
      * Return all the items
      *
+     * @see Item
+     *
      * @return array An array of items
      */
     public function all()
@@ -34,6 +49,8 @@ public function all()
     /**
      * Replace the contents of this bag with the specified items
      *
+     * @see Item
+     *
      * @param array $items An array of items
      */
     public function replace(array $items = array())
@@ -48,6 +65,8 @@ public function replace(array $items = array())
     /**
      * Add an item to the bag
      *
+     * @see Item
+     *
      * @param ItemInterface|array $item An existing item, or associative array of item parameters
      */
     public function add($item)

src/Omnipay/Common/ItemInterface.php

@@ -1,9 +1,15 @@
 <?php
+/**
+ * Cart Item interface
+ */
 
 namespace Omnipay\Common;
 
 /**
  * Cart Item interface
+ *
+ * This interface defines the functionality that all cart items in
+ * the Omnipay system are to have.
  */
 interface ItemInterface
 {

src/Omnipay/Common/PaymentMethod.php

@@ -1,13 +1,35 @@
 <?php
+/**
+ * Payment Method
+ */
 
 namespace Omnipay\Common;
 
 /**
  * Payment Method
+ *
+ * This class defines a payment method to be used in the Omnipay system.
+ *
+ * @see Issuer
  */
 class PaymentMethod
 {
+
+    /**
+     * The ID of the payment method.  Used as the payment method ID in the
+     * Issuer class.
+     *
+     * @see Issuer
+     *
+     * @var string
+     */
     protected $id;
+
+    /**
+     * The full name of the payment method
+     *
+     * @var string
+     */
     protected $name;
 
     /**

src/Omnipay/Omnipay.php

@@ -1,4 +1,7 @@
 <?php
+/**
+ * Omnipay class
+ */
 
 namespace Omnipay;
 
@@ -7,15 +10,25 @@
 /**
  * Omnipay class
  *
- * Provides static access to the gateway factory methods
+ * Provides static access to the gateway factory methods.
+ *
+ * @see Omnipay\Common\GatewayFactory
  */
 class Omnipay
 {
+
+    /**
+     * Internal factory storage
+     *
+     * @var GatewayFactory
+     */
     private static $factory;
 
     /**
      * Get the gateway factory
      *
+     * Creates a new empty GatewayFactory if none has been set previously.
+     *
      * @return GatewayFactory A GatewayFactory instance
      */
     public static function getFactory()
@@ -37,6 +50,15 @@ public static function setFactory(GatewayFactory $factory = null)
         static::$factory = $factory;
     }
 
+    /**
+     * Static function call router.
+     *
+     * All other function calls to the Omnipay class are routed to the
+     * factory.  e.g. Omnipay::Mugwump(1, 2, 3, 4) is routed to the
+     * factory's Mugwump method and passed the parameters 1, 2, 3, 4.
+     *
+     * @param mixed Parameters passed to the factory method.
+     */
     public static function __callStatic($method, $parameters)
     {
         $factory = static::getFactory();