Better PHPDoc

.php_cs.dist

@@ -55,7 +55,9 @@ return PhpCsFixer\Config::create()
         'no_alternative_syntax' => true,
         'no_binary_string' => true,
         'no_blank_lines_after_class_opening' => true,
+        'no_blank_lines_after_phpdoc' => true,
         'no_empty_comment' => true,
+        'no_empty_phpdoc' => true,
         'no_empty_statement' => true,
         'no_extra_blank_lines' => true,
         'no_homoglyph_names' => true,
@@ -84,6 +86,27 @@ return PhpCsFixer\Config::create()
         'non_printable_character' => true,
         'normalize_index_brace' => true,
         'object_operator_without_whitespace' => 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_order' => true,
+        'phpdoc_return_self_reference' => true,
+        'phpdoc_scalar' => true,
+        'phpdoc_separation' => true,
+        'phpdoc_single_line_var_spacing' => true,
+        'phpdoc_to_comment' => 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,
         'php_unit_construct' => true,
         'php_unit_fqcn_annotation' => true,
         'php_unit_method_casing' => true,

lib/Account.php

@@ -5,26 +5,26 @@
 /**
  * Class Account
  *
- * @property string $id
- * @property string $object
- * @property \Stripe\StripeObject|null $business_profile
- * @property string|null $business_type
+ * @property string $id Unique identifier for the object.
+ * @property string $object String representing the object's type. Objects of the same type share the same value.
+ * @property \Stripe\StripeObject|null $business_profile Business information about the account.
+ * @property string|null $business_type The business type.
  * @property \Stripe\StripeObject $capabilities
- * @property bool $charges_enabled
+ * @property bool $charges_enabled Whether the account can create live charges.
  * @property \Stripe\StripeObject $company
- * @property string $country
- * @property int $created
- * @property string $default_currency
- * @property bool $details_submitted
- * @property string|null $email
- * @property \Stripe\Collection $external_accounts
+ * @property string $country The account's country.
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
+ * @property string $default_currency Three-letter ISO currency code representing the default currency for the account. This must be a currency that <a href="https://stripe.com/docs/payouts">Stripe supports in the account's country</a>.
+ * @property bool $details_submitted Whether account details have been submitted. Standard accounts cannot receive payouts before this is true.
+ * @property string|null $email The primary user's email address.
+ * @property \Stripe\Collection $external_accounts External accounts (bank accounts and debit cards) currently attached to this account
  * @property \Stripe\Person $individual
- * @property \Stripe\StripeObject $metadata
- * @property bool $payouts_enabled
+ * @property \Stripe\StripeObject $metadata Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
+ * @property bool $payouts_enabled Whether Stripe can send payouts to this account.
  * @property \Stripe\StripeObject $requirements
- * @property \Stripe\StripeObject|null $settings
+ * @property \Stripe\StripeObject|null $settings Options for customizing how the account functions within Stripe.
  * @property \Stripe\StripeObject $tos_acceptance
- * @property string $type
+ * @property string $type The Stripe account type. Can be <code>standard</code>, <code>express</code>, or <code>custom</code>.
  *
  * @package Stripe
  */
@@ -44,14 +44,16 @@ class Account extends ApiResource
 
     /**
      * Possible string representations of an account's business type.
-     * @link https://stripe.com/docs/api/accounts/object#account_object-business_type
+     *
+     * @see https://stripe.com/docs/api/accounts/object#account_object-business_type
      */
     const BUSINESS_TYPE_COMPANY    = 'company';
     const BUSINESS_TYPE_INDIVIDUAL = 'individual';
 
     /**
      * Possible string representations of an account's capabilities.
-     * @link https://stripe.com/docs/api/accounts/object#account_object-capabilities
+     *
+     * @see https://stripe.com/docs/api/accounts/object#account_object-capabilities
      */
     const CAPABILITY_CARD_PAYMENTS     = 'card_payments';
     const CAPABILITY_LEGACY_PAYMENTS   = 'legacy_payments';
@@ -60,15 +62,17 @@ class Account extends ApiResource
 
     /**
      * Possible string representations of an account's capability status.
-     * @link https://stripe.com/docs/api/accounts/object#account_object-capabilities
+     *
+     * @see https://stripe.com/docs/api/accounts/object#account_object-capabilities
      */
     const CAPABILITY_STATUS_ACTIVE   = 'active';
     const CAPABILITY_STATUS_INACTIVE = 'inactive';
     const CAPABILITY_STATUS_PENDING  = 'pending';
 
     /**
      * Possible string representations of an account's type.
-     * @link https://stripe.com/docs/api/accounts/object#account_object-type
+     *
+     * @see https://stripe.com/docs/api/accounts/object#account_object-type
      */
     const TYPE_CUSTOM   = 'custom';
     const TYPE_EXPRESS  = 'express';

lib/AccountLink.php

@@ -5,10 +5,10 @@
 /**
  * Class AccountLink
  *
- * @property string $object
- * @property int $created
- * @property int $expires_at
- * @property string $url
+ * @property string $object String representing the object's type. Objects of the same type share the same value.
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
+ * @property int $expires_at The timestamp at which this account link will expire.
+ * @property string $url The URL for the account link.
  *
  * @package Stripe
  */

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)
     {
@@ -102,9 +104,9 @@ private static function _encodeObjects($d)
      * @param array|null $params
      * @param array|null $headers
      *
-     * @return array tuple containing (ApiReponse, API key)
-     *
      * @throws Exception\ApiErrorException
+     *
+     * @return array tuple containing (ApiReponse, API key)
      */
     public function request($method, $url, $params = null, $headers = null)
     {
@@ -196,7 +198,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
@@ -229,9 +231,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)
     {
@@ -293,10 +295,10 @@ private static function _defaultHeaders($apiKey, $clientInfo = null)
      * @param array $params
      * @param array $headers
      *
-     * @return array
-     *
      * @throws Exception\AuthenticationException
      * @throws Exception\ApiConnectionException
+     *
+     * @return array
      */
     private function _requestRaw($method, $url, $params, $headers)
     {
@@ -382,9 +384,9 @@ private function _requestRaw($method, $url, $params, $headers)
     /**
      * @param resource $resource
      *
-     * @return \CURLFile|string
-     *
      * @throws Exception\InvalidArgumentException
+     *
+     * @return \CURLFile|string
      */
     private function _processResourceParam($resource)
     {
@@ -410,10 +412,10 @@ private function _processResourceParam($resource)
      * @param int    $rcode
      * @param array  $rheaders
      *
-     * @return array
-     *
      * @throws Exception\UnexpectedValueException
      * @throws Exception\ApiErrorException
+     *
+     * @return array
      */
     private function _interpretResponse($rbody, $rcode, $rheaders)
     {

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,
@@ -48,9 +48,9 @@ public function __set($k, $v)
     }
 
     /**
-     * @return ApiResource The refreshed resource.
-     *
      * @throws Exception\ApiErrorException
+     *
+     * @return ApiResource The refreshed resource.
      */
     public function refresh()
     {
@@ -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/ApplePayDomain.php

@@ -5,11 +5,11 @@
 /**
  * Class ApplePayDomain
  *
- * @property string $id
- * @property string $object
- * @property int $created
+ * @property string $id Unique identifier for the object.
+ * @property string $object String representing the object's type. Objects of the same type share the same value.
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
  * @property string $domain_name
- * @property bool $livemode
+ * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
  *
  * @package Stripe
  */

lib/ApplicationFee.php

@@ -5,20 +5,20 @@
 /**
  * Class ApplicationFee
  *
- * @property string $id
- * @property string $object
- * @property string|\Stripe\Account $account
- * @property int $amount
- * @property int $amount_refunded
- * @property string|\Stripe\StripeObject $application
- * @property string|\Stripe\BalanceTransaction|null $balance_transaction
- * @property string|\Stripe\Charge $charge
- * @property int $created
- * @property string $currency
- * @property bool $livemode
- * @property string|\Stripe\Charge|null $originating_transaction
- * @property bool $refunded
- * @property \Stripe\Collection $refunds
+ * @property string $id Unique identifier for the object.
+ * @property string $object String representing the object's type. Objects of the same type share the same value.
+ * @property string|\Stripe\Account $account ID of the Stripe account this fee was taken from.
+ * @property int $amount Amount earned, in %s.
+ * @property int $amount_refunded Amount in %s refunded (can be less than the amount attribute on the fee if a partial refund was issued)
+ * @property string|\Stripe\StripeObject $application ID of the Connect application that earned the fee.
+ * @property string|\Stripe\BalanceTransaction|null $balance_transaction Balance transaction that describes the impact of this collected application fee on your account balance (not including refunds).
+ * @property string|\Stripe\Charge $charge ID of the charge that the application fee was taken from.
+ * @property int $created Time at which the object was created. Measured in seconds since the Unix epoch.
+ * @property string $currency Three-letter <a href="https://www.iso.org/iso-4217-currency-codes.html">ISO currency code</a>, in lowercase. Must be a <a href="https://stripe.com/docs/currencies">supported currency</a>.
+ * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
+ * @property string|\Stripe\Charge|null $originating_transaction ID of the corresponding charge on the platform account, if this fee was the result of a charge using the <code>destination</code> parameter.
+ * @property bool $refunded Whether the fee has been fully refunded. If the fee is only partially refunded, this attribute will still be false.
+ * @property \Stripe\Collection $refunds A list of refunds that have been applied to the fee.
  *
  * @package Stripe
  */

lib/Balance.php

@@ -5,11 +5,11 @@
 /**
  * Class Balance
  *
- * @property string $object
- * @property \Stripe\StripeObject[] $available
- * @property \Stripe\StripeObject[] $connect_reserved
- * @property bool $livemode
- * @property \Stripe\StripeObject[] $pending
+ * @property string $object String representing the object's type. Objects of the same type share the same value.
+ * @property \Stripe\StripeObject[] $available Funds that are available to be transferred or paid out, whether automatically by Stripe or explicitly via the <a href="#transfers">Transfers API</a> or <a href="#payouts">Payouts API</a>. The available balance for each currency and payment type can be found in the <code>source_types</code> property.
+ * @property \Stripe\StripeObject[] $connect_reserved Funds held due to negative balances on connected Custom accounts. The connect reserve balance for each currency and payment type can be found in the <code>source_types</code> property.
+ * @property bool $livemode Has the value <code>true</code> if the object exists in live mode or the value <code>false</code> if the object exists in test mode.
+ * @property \Stripe\StripeObject[] $pending Funds that are not yet available in the balance, due to the 7-day rolling pay cycle. The pending balance for each currency, and for each payment type, can be found in the <code>source_types</code> property.
  *
  * @package Stripe
  */