Merge pull request #15 from MarketDataApp/add-comments-for-php-doc

Add updated doc strings for php doc

Author: KerryJones

src/Client.php

@@ -9,17 +9,27 @@
 use MarketDataApp\Endpoints\Stocks;
 use MarketDataApp\Endpoints\Utilities;
 
+/**
+ * Client class for the Market Data API.
+ *
+ * This class provides access to various endpoints of the Market Data API,
+ * including indices, stocks, options, markets, mutual funds, and utilities.
+ */
 class Client extends ClientBase
 {
 
     /**
      * The index endpoints provided by the Market Data API offer access to both real-time and historical data related to
      * financial indices. These endpoints are designed to cater to a wide range of financial data needs.
+     *
+     * @var Indices
      */
     public Indices $indices;
 
     /**
      * Stock endpoints include numerous fundamental, technical, and pricing data.
+     *
+     * @var Stocks
      */
     public Stocks $stocks;
 
@@ -28,25 +38,40 @@ class Client extends ClientBase
      * around options data. These endpoints are designed to be flexible and robust, supporting both real-time
      * and historical data queries. They accommodate a wide range of optional parameters for detailed data
      * retrieval, making the Market Data API a versatile tool for options traders and financial analysts.
+     *
+     * @var Options
      */
     public Options $options;
 
     /**
      * The Markets endpoints provide reference and status data about the markets covered by Market Data.
+     *
+     * @var Markets
      */
     public Markets $markets;
 
     /**
      * The mutual funds endpoints offer access to historical pricing data for mutual funds.
+     *
+     * @var MutualFunds
      */
     public MutualFunds $mutual_funds;
 
     /**
      * These endpoints are designed to assist with API-related service issues, including checking the online status and
      * uptime.
+     *
+     * @var Utilities
      */
     public Utilities $utilities;
 
+    /**
+     * Constructor for the Client class.
+     *
+     * Initializes all endpoint classes with the provided API token.
+     *
+     * @param string $token The API token for authentication.
+     */
     public function __construct($token)
     {
         parent::__construct($token);

src/ClientBase.php

@@ -8,27 +8,62 @@
 use GuzzleHttp\Promise\PromiseInterface;
 use MarketDataApp\Exceptions\ApiException;
 
+/**
+ * Abstract base class for Market Data API client.
+ *
+ * This class provides core functionality for API communication,
+ * including parallel execution, async requests, and response handling.
+ */
 abstract class ClientBase
 {
 
+    /**
+     * The base URL for the Market Data API.
+     */
     public const API_URL = "https://api.marketdata.app/";
+
+    /**
+     * The host for the Market Data API.
+     */
     public const API_HOST = "api.marketdata.app";
 
+    /**
+     * @var GuzzleClient The Guzzle HTTP client instance.
+     */
     protected GuzzleClient $guzzle;
+
+    /**
+     * @var string The API token for authentication.
+     */
     protected string $token;
 
+    /**
+     * ClientBase constructor.
+     *
+     * @param string $token The API token for authentication.
+     */
     public function __construct(string $token)
     {
         $this->guzzle = new GuzzleClient(['base_uri' => self::API_URL]);
         $this->token = $token;
     }
 
+    /**
+     * Set a custom Guzzle client.
+     *
+     * @param GuzzleClient $guzzleClient The Guzzle client to use.
+     */
     public function setGuzzle(GuzzleClient $guzzleClient): void
     {
         $this->guzzle = $guzzleClient;
     }
 
     /**
+     * Execute multiple API calls in parallel.
+     *
+     * @param array $calls An array of method calls, each containing the method name and arguments.
+     *
+     * @return array An array of decoded JSON responses.
      * @throws \Throwable
      */
     public function execute_in_parallel(array $calls): array
@@ -44,6 +79,14 @@ public function execute_in_parallel(array $calls): array
         }, $responses);
     }
 
+    /**
+     * Perform an asynchronous API request.
+     *
+     * @param string $method    The API method to call.
+     * @param array  $arguments The arguments for the API call.
+     *
+     * @return PromiseInterface
+     */
     protected function async($method, array $arguments = []): PromiseInterface
     {
         return $this->guzzle->getAsync($method, [
@@ -53,6 +96,12 @@ protected function async($method, array $arguments = []): PromiseInterface
     }
 
     /**
+     * Execute a single API request.
+     *
+     * @param string $method    The API method to call.
+     * @param array  $arguments The arguments for the API call.
+     *
+     * @return object The API response as an object.
      * @throws GuzzleException
      * @throws ApiException
      */
@@ -93,6 +142,13 @@ public function execute($method, array $arguments = []): object
         return $object_response;
     }
 
+    /**
+     * Generate headers for API requests.
+     *
+     * @param string $format The desired response format (json, csv, or html).
+     *
+     * @return array An array of headers.
+     */
     protected function headers(string $format = 'json'): array
     {
         return [

src/Endpoints/Indices.php

@@ -11,14 +11,25 @@
 use MarketDataApp\Exceptions\ApiException;
 use MarketDataApp\Traits\UniversalParameters;
 
+/**
+ * Indices class for handling index-related API endpoints.
+ */
 class Indices
 {
 
     use UniversalParameters;
 
+    /** @var Client The Market Data API client instance. */
     private Client $client;
+
+    /** @var string The base URL for index endpoints. */
     public const BASE_URL = "v1/indices/";
 
+    /**
+     * Indices constructor.
+     *
+     * @param Client $client The Market Data API client instance.
+     */
     public function __construct($client)
     {
         $this->client = $client;
@@ -27,13 +38,15 @@ public function __construct($client)
     /**
      * Get a real-time quote for an index.
      *
-     * @param string $symbol The index symbol, without any leading or trailing index identifiers. For example, use DJI
-     * do not use $DJI, ^DJI, .DJI, DJI.X, etc.
+     * @param string          $symbol         The index symbol, without any leading or trailing index identifiers. For
+     *                                        example, use DJI do not use $DJI, ^DJI, .DJI, DJI.X, etc.
      *
-     * @param bool $fifty_two_week Enable the output of 52-week high and 52-week low data in the quote output.
+     * @param bool            $fifty_two_week Enable the output of 52-week high and 52-week low data in the quote
+     *                                        output.
      *
-     * @param Parameters|null $parameters Universal parameters for all methods (such as format).
+     * @param Parameters|null $parameters     Universal parameters for all methods (such as format).
      *
+     * @return Quote
      * @throws GuzzleException|ApiException
      */
     public function quote(
@@ -44,14 +57,15 @@ public function quote(
         return new Quote($this->execute("quotes/$symbol", ['52week' => $fifty_two_week], $parameters));
     }
 
-
     /**
-     * Get a real-time price quote for a multiple indices by doing parallel requests.
+     * Get real-time price quotes for multiple indices by doing parallel requests.
      *
-     * @param array $symbols The ticker symbols to return in the response.
-     * @param bool $fifty_two_week Enable the output of 52-week high and 52-week low data in the quote output.
-     * @param Parameters|null $parameters Universal parameters for all methods (such as format).
+     * @param array           $symbols        The ticker symbols to return in the response.
+     * @param bool            $fifty_two_week Enable the output of 52-week high and 52-week low data in the quote
+     *                                        output.
+     * @param Parameters|null $parameters     Universal parameters for all methods (such as format).
      *
+     * @return Quotes
      * @throws \Throwable
      */
     public function quotes(
@@ -71,27 +85,27 @@ public function quotes(
     /**
      * Get historical price candles for an index.
      *
-     * @param string $symbol The index symbol, without any leading or trailing index identifiers. For example, use DJI
-     * do not use $DJI, ^DJI, .DJI, DJI.X, etc.
+     * @param string          $symbol     The index symbol, without any leading or trailing index identifiers. For
+     *                                    example, use DJI do not use $DJI, ^DJI, .DJI, DJI.X, etc.
      *
-     * @param string $from The leftmost candle on a chart (inclusive). If you use countback, to is not required.
-     * Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
+     * @param string          $from       The leftmost candle on a chart (inclusive). If you use countback, to is not
+     *                                    required. Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
      *
-     * @param string|null $to The rightmost candle on a chart (inclusive). Accepted timestamp inputs: ISO 8601, unix,
-     * spreadsheet.
+     * @param string|null     $to         The rightmost candle on a chart (inclusive). Accepted timestamp inputs: ISO
+     *                                    8601, unix, spreadsheet.
      *
-     * @param string $resolution The duration of each candle.
-     * Minutely Resolutions: (minutely, 1, 3, 5, 15, 30, 45, ...) Hourly Resolutions: (hourly, H, 1H, 2H, ...)
-     * Daily Resolutions: (daily, D, 1D, 2D, ...)
-     * Weekly Resolutions: (weekly, W, 1W, 2W, ...)
-     * Monthly Resolutions: (monthly, M, 1M, 2M, ...)
-     * Yearly Resolutions:(yearly, Y, 1Y, 2Y, ...)
+     * @param string          $resolution The duration of each candle.
+     *                                    Minutely Resolutions: (minutely, 1, 3, 5, 15, 30, 45, ...) Hourly
+     *                                    Resolutions: (hourly, H, 1H, 2H, ...) Daily Resolutions: (daily, D, 1D, 2D,
+     *                                    ...) Weekly Resolutions: (weekly, W, 1W, 2W, ...) Monthly Resolutions:
+     *                                    (monthly, M, 1M, 2M, ...) Yearly Resolutions:(yearly, Y, 1Y, 2Y, ...)
      *
-     * @param int|null $countback Will fetch a number of candles before (to the left of) to. If you use from, countback
-     * is not required.
+     * @param int|null        $countback  Will fetch a number of candles before (to the left of) to. If you use from,
+     *                                    countback is not required.
      *
      * @param Parameters|null $parameters Universal parameters for all methods (such as format).
      *
+     * @return Candles
      * @throws ApiException|GuzzleException
      */
     public function candles(

src/Endpoints/Markets.php

@@ -9,40 +9,55 @@
 use MarketDataApp\Exceptions\ApiException;
 use MarketDataApp\Traits\UniversalParameters;
 
+/**
+ * Markets class for handling market-related API endpoints.
+ */
 class Markets
 {
 
     use UniversalParameters;
 
+    /** @var Client The Market Data API client instance. */
     private Client $client;
+
+    /** @var string The base URL for market endpoints. */
     public const BASE_URL = "v1/markets/";
 
+    /**
+     * Markets constructor.
+     *
+     * @param Client $client The Market Data API client instance.
+     */
     public function __construct($client)
     {
         $this->client = $client;
     }
 
     /**
+     * Get the market status for a specific country and date range.
+     *
      * Get the past, present, or future status for a stock market. The endpoint will respond with "open" for trading
      * days or "closed" for weekends or market holidays.
      *
-     * @param string $country The country. Use the two-digit ISO 3166 country code. If no country is specified, US will
-     * be assumed. Only countries that Market Data supports for stock price data are available (currently only the
-     * United States).
+     * @param string          $country    The country. Use the two-digit ISO 3166 country code. If no country is
+     *                                    specified, US will be assumed. Only countries that Market Data supports for
+     *                                    stock price data are available (currently only the United States).
      *
-     * @param string|null $date Consult whether the market was open or closed on the specified date. Accepted timestamp
-     * inputs: ISO 8601, unix, spreadsheet.
+     * @param string|null     $date       Consult whether the market was open or closed on the specified date. Accepted
+     *                                    timestamp inputs: ISO 8601, unix, spreadsheet.
      *
-     * @param string|null $from The earliest date (inclusive). If you use countback, from is not required. Accepted
-     * timestamp inputs: ISO 8601, unix, spreadsheet.
+     * @param string|null     $from       The earliest date (inclusive). If you use countback, from is not required.
+     *                                    Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
      *
-     * @param string|null $to The last date (inclusive). Accepted timestamp inputs: ISO 8601, unix, spreadsheet.
+     * @param string|null     $to         The last date (inclusive). Accepted timestamp inputs: ISO 8601, unix,
+     *                                    spreadsheet.
      *
-     * @param int|null $countback Countback will fetch a number of dates before to If you use from, countback is not
-     * required.
+     * @param int|null        $countback  Countback will fetch a number of dates before to If you use from, countback
+     *                                    is not required.
      *
      * @param Parameters|null $parameters Universal parameters for all methods (such as format).
      *
+     * @return Statuses
      * @throws GuzzleException|ApiException
      */
     public function status(