Annotations for optional methods on GatewayInterface

This should help IDE's with code completion and suggestions on the gateway methods and return values (which doesn't work very well at the moment).

I understand that these methods are optional - so this may not be the right way to address this issue. My personal opinion is that documenting the method as optional in the annotation is better than not documenting it all.

There are also lots of methods in the AbstractGateway that I think should be included in the GatewayInterface (supportsAuthorize, supportsCompleteAuthorize, supportsCapture, etc...). I wanted to know peoples thoughts on this before I spent the time on a PR.

Author: AndrewCarterUK

src/Omnipay/Common/GatewayInterface.php

@@ -12,6 +12,17 @@
  * Omnipay gateway needs to define.
  *
  * @see AbstractGateway
+ * 
+ * @method \Omnipay\Common\Message\ResponseInterface authorize(array $options = array())         (Optional method) Authorize an amount on the customers card
+ * @method \Omnipay\Common\Message\ResponseInterface completeAuthorize(array $options = array()) (Optional method) Handle return from off-site gateways after authorization
+ * @method \Omnipay\Common\Message\ResponseInterface capture(array $options = array())           (Optional method) Capture an amount you have previously authorized
+ * @method \Omnipay\Common\Message\ResponseInterface purchase(array $options = array())          (Optional method) Authorize and immediately capture an amount on the customers card
+ * @method \Omnipay\Common\Message\ResponseInterface completePurchase(array $options = array())  (Optional method) Handle return from off-site gateways after purchase
+ * @method \Omnipay\Common\Message\ResponseInterface refund(array $options = array())            (Optional method) Refund an already processed transaction
+ * @method \Omnipay\Common\Message\ResponseInterface void(array $options = array())              (Optional method) Generally can only be called up to 24 hours after submitting a transaction
+ * @method \Omnipay\Common\Message\ResponseInterface createCard(array $options = array())        (Optional method) The returned response object includes a cardReference, which can be used for future transactions
+ * @method \Omnipay\Common\Message\ResponseInterface updateCard(array $options = array())        (Optional method) Update a stored card
+ * @method \Omnipay\Common\Message\ResponseInterface deleteCard(array $options = array())        (Optional method) Delete a stored card
  */
 interface GatewayInterface
 {