From 1661d84890ee474a7b1ce3ae4dcc20c4ff0d3c1d Mon Sep 17 00:00:00 2001
From: Del <del@babel.com.au>
Date: Sun, 11 Jan 2015 11:41:45 +0700
Subject: [PATCH] Adding documentation, adding documentation generation script

---
 .gitignore                              |  3 +++
 makedoc.sh                              | 23 ++++++++++++++++++++
 src/Omnipay/Common/AbstractGateway.php  |  8 +++++++
 src/Omnipay/Common/CreditCard.php       |  6 +++++
 src/Omnipay/Common/Currency.php         |  7 ++++++
 src/Omnipay/Common/GatewayFactory.php   | 14 ++++++++++++
 src/Omnipay/Common/GatewayInterface.php |  6 +++++
 src/Omnipay/Common/Helper.php           | 12 ++++++++++
 src/Omnipay/Common/Issuer.php           | 29 +++++++++++++++++++++++++
 src/Omnipay/Common/Item.php             |  7 ++++++
 src/Omnipay/Common/ItemBag.php          | 19 ++++++++++++++++
 src/Omnipay/Common/ItemInterface.php    |  6 +++++
 src/Omnipay/Common/PaymentMethod.php    | 22 +++++++++++++++++++
 src/Omnipay/Omnipay.php                 | 24 +++++++++++++++++++-
 14 files changed, 185 insertions(+), 1 deletion(-)
 create mode 100755 makedoc.sh

diff --git a/.gitignore b/.gitignore
index 8a282a56..389e6006 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,3 +2,6 @@
 composer.lock
 composer.phar
 phpunit.xml
+.directory
+reports/
+documents/
diff --git a/makedoc.sh b/makedoc.sh
new file mode 100755
index 00000000..4b8be761
--- /dev/null
+++ b/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
diff --git a/src/Omnipay/Common/AbstractGateway.php b/src/Omnipay/Common/AbstractGateway.php
index d5fc17ce..a93635c2 100644
--- a/src/Omnipay/Common/AbstractGateway.php
+++ b/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
 {
diff --git a/src/Omnipay/Common/CreditCard.php b/src/Omnipay/Common/CreditCard.php
index e020aefc..53adf66d 100644
--- a/src/Omnipay/Common/CreditCard.php
+++ b/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
 {
diff --git a/src/Omnipay/Common/Currency.php b/src/Omnipay/Common/Currency.php
index daac87f8..9226e1e4 100644
--- a/src/Omnipay/Common/Currency.php
+++ b/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
 {
diff --git a/src/Omnipay/Common/GatewayFactory.php b/src/Omnipay/Common/GatewayFactory.php
index 2090d891..b4ade5a2 100644
--- a/src/Omnipay/Common/GatewayFactory.php
+++ b/src/Omnipay/Common/GatewayFactory.php
@@ -1,4 +1,7 @@
 <?php
+/**
+ * Omnipay Gateway Factory class
+ */
 
 namespace Omnipay\Common;
 
@@ -6,8 +9,19 @@
 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();
 
     /**
diff --git a/src/Omnipay/Common/GatewayInterface.php b/src/Omnipay/Common/GatewayInterface.php
index 701d7283..c8724998 100644
--- a/src/Omnipay/Common/GatewayInterface.php
+++ b/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
 {
diff --git a/src/Omnipay/Common/Helper.php b/src/Omnipay/Common/Helper.php
index 82d0f177..0c943c8c 100644
--- a/src/Omnipay/Common/Helper.php
+++ b/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)
     {
diff --git a/src/Omnipay/Common/Issuer.php b/src/Omnipay/Common/Issuer.php
index 91f2d7f8..fcbfc327 100644
--- a/src/Omnipay/Common/Issuer.php
+++ b/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()
diff --git a/src/Omnipay/Common/Item.php b/src/Omnipay/Common/Item.php
index 301bd80d..d56413a6 100644
--- a/src/Omnipay/Common/Item.php
+++ b/src/Omnipay/Common/Item.php
@@ -1,4 +1,7 @@
 <?php
+/**
+ * Cart Item
+ */
 
 namespace Omnipay\Common;
 
@@ -6,6 +9,10 @@
 
 /**
  * Cart Item
+ *
+ * This class defines a single cart item in the Omnipay system.
+ *
+ * @see ItemInterface
  */
 class Item implements ItemInterface
 {
diff --git a/src/Omnipay/Common/ItemBag.php b/src/Omnipay/Common/ItemBag.php
index d5caa28b..f726c3b7 100644
--- a/src/Omnipay/Common/ItemBag.php
+++ b/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)
diff --git a/src/Omnipay/Common/ItemInterface.php b/src/Omnipay/Common/ItemInterface.php
index c4035153..9380e65c 100644
--- a/src/Omnipay/Common/ItemInterface.php
+++ b/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
 {
diff --git a/src/Omnipay/Common/PaymentMethod.php b/src/Omnipay/Common/PaymentMethod.php
index ff23ef7f..5f14b16e 100644
--- a/src/Omnipay/Common/PaymentMethod.php
+++ b/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;
 
     /**
diff --git a/src/Omnipay/Omnipay.php b/src/Omnipay/Omnipay.php
index a43576c5..dcb958d4 100644
--- a/src/Omnipay/Omnipay.php
+++ b/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();