Merge pull request #863 from stripe/ob-phpdoc

Use PHP-CS-Fixer rules to improve PHPDoc

.php_cs.dist

@@ -13,5 +13,24 @@ return PhpCsFixer\Config::create()
         ],
         'linebreak_after_opening_tag' => true,
         'native_function_invocation' => true,
+        'phpdoc_add_missing_param_annotation' => true,
+        'phpdoc_indent' => true,
+        'phpdoc_inline_tag' => true,
+        'phpdoc_no_access' => true,
+        'phpdoc_no_alias_tag' => true,
+        'phpdoc_no_empty_return' => true,
+        'phpdoc_no_useless_inheritdoc' => true,
+        'phpdoc_return_self_reference' => true,
+        'phpdoc_scalar' => true,
+        'phpdoc_separation' => true,
+        'phpdoc_single_line_var_spacing' => true,
+        'phpdoc_trim' => true,
+        'phpdoc_trim_consecutive_blank_line_separation' => true,
+        'phpdoc_types' => true,
+        'phpdoc_types_order' => [
+            'null_adjustment' => 'always_last',
+        ],
+        'phpdoc_var_annotation_correct_order' => true,
+        'phpdoc_var_without_name' => true,
     ])
 ;

lib/AlipayAccount.php

@@ -8,7 +8,7 @@
  * @package Stripe
  *
  * @deprecated Alipay accounts are deprecated. Please use the sources API instead.
- * @link https://stripe.com/docs/sources/alipay
+ * @see https://stripe.com/docs/sources/alipay
  */
 class AlipayAccount extends ApiResource
 {
@@ -43,7 +43,7 @@ public function instanceUrl()
      * @throws \Stripe\Exception\BadMethodCallException
      *
      * @deprecated Alipay accounts are deprecated. Please use the sources API instead.
-     * @link https://stripe.com/docs/sources/alipay
+     * @see https://stripe.com/docs/sources/alipay
      */
     public static function retrieve($_id, $_opts = null)
     {
@@ -61,7 +61,7 @@ public static function retrieve($_id, $_opts = null)
      * @throws \Stripe\Exception\BadMethodCallException
      *
      * @deprecated Alipay accounts are deprecated. Please use the sources API instead.
-     * @link https://stripe.com/docs/sources/alipay
+     * @see https://stripe.com/docs/sources/alipay
      */
     public static function update($_id, $_params = null, $_options = null)
     {

lib/ApiOperations/Request.php

@@ -10,7 +10,7 @@
 trait Request
 {
     /**
-     * @param array|null|mixed $params The list of parameters to validate
+     * @param array|mixed|null $params The list of parameters to validate
      *
      * @throws \Stripe\Exception\InvalidArgumentException if $params exists and is not an array
      */

lib/ApiRequestor.php

@@ -46,9 +46,11 @@ public function __construct($apiKey = null, $apiBase = null)
 
     /**
      * Creates a telemetry json blob for use in 'X-Stripe-Client-Telemetry' headers
+     *
      * @static
      *
      * @param RequestTelemetry $requestTelemetry
+     *
      * @return string
      */
     private static function _telemetryJson($requestTelemetry)
@@ -71,9 +73,9 @@ private static function _telemetryJson($requestTelemetry)
     /**
      * @static
      *
-     * @param ApiResource|bool|array|mixed $d
+     * @param ApiResource|array|bool|mixed $d
      *
-     * @return ApiResource|array|string|mixed
+     * @return ApiResource|array|mixed|string
      */
     private static function _encodeObjects($d)
     {
@@ -194,7 +196,7 @@ private static function _specificAPIError($rbody, $rcode, $rheaders, $resp, $err
     /**
      * @static
      *
-     * @param string|bool $rbody
+     * @param bool|string $rbody
      * @param int         $rcode
      * @param array       $rheaders
      * @param array       $resp
@@ -227,9 +229,9 @@ private static function _specificOAuthError($rbody, $rcode, $rheaders, $resp, $e
     /**
      * @static
      *
-     * @param null|array $appInfo
+     * @param array|null $appInfo
      *
-     * @return null|string
+     * @return string|null
      */
     private static function _formatAppInfo($appInfo)
     {

lib/ApiResource.php

@@ -28,7 +28,7 @@ public static function getSavedNestedResources()
     }
 
     /**
-     * @var boolean A flag that can be set a behavior that will cause this
+     * @var bool A flag that can be set a behavior that will cause this
      * resource to be encoded and sent up along with an update of its parent
      * resource. This is usually not desirable because resources are updated
      * individually on their own endpoints, but there are certain cases,
@@ -88,6 +88,10 @@ public static function classUrl()
     }
 
     /**
+     * @param string|null $id the ID of the resource
+     *
+     * @throws Exception\UnexpectedValueException if $id is null
+     *
      * @return string The instance endpoint URL for the given class.
      */
     public static function resourceUrl($id)

lib/ApiResponse.php

@@ -33,7 +33,7 @@ class ApiResponse
 
     /**
      * @param string $body
-     * @param integer $code
+     * @param int $code
      * @param array|CaseInsensitiveArray|null $headers
      * @param array|null $json
      */

lib/Capability.php

@@ -23,7 +23,8 @@ class Capability extends ApiResource
 
     /**
      * Possible string representations of a capability's status.
-     * @link https://stripe.com/docs/api/capabilities/object#capability_object-status
+     *
+     * @see https://stripe.com/docs/api/capabilities/object#capability_object-status
      */
     const STATUS_ACTIVE      = 'active';
     const STATUS_INACTIVE    = 'inactive';

lib/Collection.php

@@ -158,6 +158,7 @@ public function autoPagingIterator()
      * behavior of the API when it attempts to return a page beyond the last.
      *
      * @param array|string|null $opts
+     *
      * @return Collection
      */
     public static function emptyCollection($opts = null)
@@ -168,7 +169,7 @@ public static function emptyCollection($opts = null)
     /**
      * Returns true if the page object contains no element.
      *
-     * @return boolean
+     * @return bool
      */
     public function isEmpty()
     {
@@ -183,6 +184,7 @@ public function isEmpty()
      *
      * @param array|null $params
      * @param array|string|null $opts
+     *
      * @return Collection
      */
     public function nextPage($params = null, $opts = null)
@@ -210,6 +212,7 @@ public function nextPage($params = null, $opts = null)
      *
      * @param array|null $params
      * @param array|string|null $opts
+     *
      * @return Collection
      */
     public function previousPage($params = null, $opts = null)

lib/CustomerBalanceTransaction.php

@@ -27,7 +27,8 @@ class CustomerBalanceTransaction extends ApiResource
 
     /**
      * Possible string representations of a balance transaction's type.
-     * @link https://stripe.com/docs/api/customers/customer_balance_transaction_object#customer_balance_transaction_object-type
+     *
+     * @see https://stripe.com/docs/api/customers/customer_balance_transaction_object#customer_balance_transaction_object-type
      */
     const TYPE_ADJUSTEMENT             = 'adjustment';
     const TYPE_APPLIED_TO_INVOICE      = 'applied_to_invoice';

lib/ErrorObject.php

@@ -38,7 +38,8 @@ class ErrorObject extends StripeObject
 {
     /**
      * Possible string representations of an error's code.
-     * @link https://stripe.com/docs/error-codes
+     *
+     * @see https://stripe.com/docs/error-codes
      */
     const CODE_ACCOUNT_ALREADY_EXISTS                     = 'account_already_exists';
     const CODE_ACCOUNT_COUNTRY_INVALID_ADDRESS            = 'account_country_invalid_address';
@@ -136,8 +137,8 @@ class ErrorObject extends StripeObject
      * Refreshes this object using the provided values.
      *
      * @param array $values
-     * @param null|string|array|Util\RequestOptions $opts
-     * @param boolean $partial Defaults to false.
+     * @param array|string|Util\RequestOptions|null $opts
+     * @param bool $partial Defaults to false.
      */
     public function refreshFrom($values, $opts, $partial = false)
     {

lib/HttpClient/ClientInterface.php

@@ -9,11 +9,12 @@ interface ClientInterface
      * @param string $absUrl The URL being requested, including domain and protocol
      * @param array $headers Headers to be used in the request (full strings, not KV pairs)
      * @param array $params KV pairs for parameters. Can be nested for arrays and hashes
-     * @param boolean $hasFile Whether or not $params references a file (via an @ prefix or
+     * @param bool $hasFile Whether or not $params references a file (via an @ prefix or
      *                         CURLFile)
      *
      * @throws \Stripe\Exception\ApiConnectionException
      * @throws \Stripe\Exception\UnexpectedValueException
+     *
      * @return array An array whose first element is raw request body, second
      *    element is HTTP status code and third array of HTTP headers.
      */

lib/HttpClient/CurlClient.php

@@ -63,6 +63,7 @@ public static function instance()
      * throw an exception if $defaultOptions returns a non-array value.
      *
      * @param array|callable|null $defaultOptions
+     * @param \Stripe\Util\RandomGenerator|null $randomGenerator
      */
     public function __construct($defaultOptions = null, $randomGenerator = null)
     {
@@ -98,31 +99,31 @@ public function getUserAgentInfo()
     }
 
     /**
-     * @return boolean
+     * @return bool
      */
     public function getEnablePersistentConnections()
     {
         return $this->enablePersistentConnections;
     }
 
     /**
-     * @param boolean $enable
+     * @param bool $enable
      */
     public function setEnablePersistentConnections($enable)
     {
         $this->enablePersistentConnections = $enable;
     }
 
     /**
-     * @return boolean
+     * @return bool
      */
     public function getEnableHttp2()
     {
         return $this->enableHttp2;
     }
 
     /**
-     * @param boolean $enable
+     * @param bool $enable
      */
     public function setEnableHttp2($enable)
     {
@@ -273,6 +274,7 @@ public function request($method, $absUrl, $headers, $params, $hasFile)
 
     /**
      * @param array $opts cURL options
+     * @param string $absUrl
      */
     private function executeRequestWithRetries($opts, $absUrl)
     {
@@ -341,6 +343,7 @@ private function executeRequestWithRetries($opts, $absUrl)
      * @param int $errno
      * @param string $message
      * @param int $numRetries
+     *
      * @throws Exception\ApiConnectionException
      */
     private function handleCurlError($url, $errno, $message, $numRetries)
@@ -504,7 +507,7 @@ private function resetCurlHandle()
     /**
      * Indicates whether it is safe to use HTTP/2 or not.
      *
-     * @return boolean
+     * @return bool
      */
     private function canSafelyUseHttp2()
     {
@@ -519,7 +522,8 @@ private function canSafelyUseHttp2()
      *
      * @param string[] $headers
      * @param string $name
-     * @return boolean
+     *
+     * @return bool
      */
     private function hasHeader($headers, $name)
     {

lib/Invoice.php

@@ -114,8 +114,8 @@ class Invoice extends ApiResource
 
     /**
      * Possible string representations of the `billing` property.
-     * @deprecated Use `collection_method` instead.
      *
+     * @deprecated Use `collection_method` instead.
      * @see https://stripe.com/docs/api/invoices/object#invoice_object-billing
      */
     const BILLING_CHARGE_AUTOMATICALLY = 'charge_automatically';

lib/OAuthErrorObject.php

@@ -16,8 +16,8 @@ class OAuthErrorObject extends StripeObject
      * Refreshes this object using the provided values.
      *
      * @param array $values
-     * @param null|string|array|Util\RequestOptions $opts
-     * @param boolean $partial Defaults to false.
+     * @param array|string|Util\RequestOptions|null $opts
+     * @param bool $partial Defaults to false.
      */
     public function refreshFrom($values, $opts, $partial = false)
     {

lib/PaymentIntent.php

@@ -56,7 +56,6 @@ class PaymentIntent extends ApiResource
     /**
      * These constants are possible representations of the status field.
      *
-     *
      * @see https://stripe.com/docs/api/payment_intents/object#payment_intent_object-status
      */
     const STATUS_CANCELED                = 'canceled';

lib/Person.php

@@ -42,14 +42,16 @@ class Person extends ApiResource
 
     /**
      * Possible string representations of a person's gender.
-     * @link https://stripe.com/docs/api/persons/object#person_object-gender
+     *
+     * @see https://stripe.com/docs/api/persons/object#person_object-gender
      */
     const GENDER_MALE   = 'male';
     const GENDER_FEMALE = 'female';
 
     /**
      * Possible string representations of a person's verification status.
-     * @link https://stripe.com/docs/api/persons/object#person_object-verification-status
+     *
+     * @see https://stripe.com/docs/api/persons/object#person_object-verification-status
      */
     const VERIFICATION_STATUS_PENDING    = 'pending';
     const VERIFICATION_STATUS_UNVERIFIED = 'unverified';

lib/RequestTelemetry.php

@@ -6,6 +6,7 @@
  * Class RequestTelemetry
  *
  * Tracks client request telemetry
+ *
  * @package Stripe
  */
 class RequestTelemetry

lib/SetupIntent.php

@@ -40,7 +40,6 @@ class SetupIntent extends ApiResource
     /**
      * These constants are possible representations of the status field.
      *
-     *
      * @see https://stripe.com/docs/api/setup_intents/object#setup_intent_object-status
      */
     const STATUS_CANCELED                = 'canceled';

lib/Stripe.php

@@ -159,15 +159,15 @@ public static function setCABundlePath($caBundlePath)
     }
 
     /**
-     * @return boolean
+     * @return bool
      */
     public static function getVerifySslCerts()
     {
         return self::$verifySslCerts;
     }
 
     /**
-     * @param boolean $verify
+     * @param bool $verify
      */
     public static function setVerifySslCerts($verify)
     {
@@ -202,8 +202,9 @@ public static function getAppInfo()
 
     /**
      * @param string $appName The application's name
-     * @param string $appVersion The application's version
-     * @param string $appUrl The application's URL
+     * @param string|null $appVersion The application's version
+     * @param string|null $appUrl The application's URL
+     * @param string|null $appPartnerId The application's partner ID
      */
     public static function setAppInfo($appName, $appVersion = null, $appUrl = null, $appPartnerId = null)
     {