Merge pull request #25 from delatbabel/master

Adding documentation, adding documentation generation script

Author: greydnls

.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
 {