Adds PHPdocs for functions & classes

src/Device/Client.php

@@ -1,20 +1,36 @@
 <?php
 
+/**
+ * Client.php
+ *
+ * (c) AMJones <am@jonesiscoding.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
 namespace DevCoding\Device;
 
 use DevCoding\Client\Object\Browser\Browser;
 use DevCoding\Client\Object\Headers\UA;
 use DevCoding\Client\Object\Headers\UAFullVersionList;
 use DevCoding\Client\Object\Version\ClientVersion;
-use DevCoding\CodeObject\Object\Base\BaseVersion;
 use DevCoding\Hints\Hint\FullVersionList;
 use DevCoding\Hints\Hint\ViewportWidth;
 use DevCoding\Hints\Hint\ViewportHeight;
 use DevCoding\Hints\Hint\UserAgent;
 
+/**
+ * Object class representing the client software of a device.
+ *
+ * @author  AMJones <am@jonesiscoding.com
+ * @license https://github.com/jonesiscoding/code-object/blob/main/LICENSE
+ */
 class Client extends DeviceChild
 {
   /**
+   * Convenience function to return a Browser object.
+   *
    * @return Browser
    */
   public function getBrowser()
@@ -23,6 +39,8 @@ public function getBrowser()
   }
 
   /**
+   * Returns a UAFullVersionList object, with the fully parsed contents of the 'Sec-CH-UA-Full-Version-List' header.
+   *
    * @return UAFullVersionList|null
    */
   public function getFullVersionList()
@@ -36,6 +54,8 @@ public function getFullVersionList()
   }
 
   /**
+   * Returns a UA object, with the fully parsed contents of the 'Sec-CH-UA' header.
+   *
    * @return UA|null
    */
   public function getUserAgent()
@@ -49,7 +69,9 @@ public function getUserAgent()
   }
 
   /**
-   * @return BaseVersion
+   * Returns a ClientVersion object, taken from the 'Sec-CH-UA-Full-Version-List' or 'Sec-CH-UA' headers.
+   *
+   * @return ClientVersion|null
    */
   public function getVersion()
   {
@@ -66,6 +88,11 @@ public function getVersion()
   }
 
   /**
+   * If available, returns the current viewport height in pixels. Note that this value is only accurate if the user has
+   * not resized the window since the last request.
+   *
+   * Value is taken from the 'vh' key of the cookie set by device.js.
+   *
    * @return float|int
    */
   public function getViewportHeight()
@@ -74,6 +101,12 @@ public function getViewportHeight()
   }
 
   /**
+   * If available, returns the current viewport with in pixels.  Note that this value is only accurate if the user has
+   * not resized the window since the last request.
+   *
+   * Value is taken from the Sec-CH-Viewport-Width or Viewport-Width headers, or alternatively from the 'vw' key of the
+   * cookie set by device.js.
+   *
    * @return float|int
    */
   public function getViewportWidth()
@@ -82,11 +115,16 @@ public function getViewportWidth()
   }
 
   /**
+   * Evaluates if the browser feature given (as a header) is supported by this client.
+   *
+   * These values are determined by information provided by the cookie set by device.js, or alternatively from CanIUse
+   * data, based on the browser detected.
+   *
    * @param string $key
    *
    * @return bool
    */
-  public function isSupported($key)
+  public function isSupported($key): bool
   {
     return $this->ClientHints->bool($key);
   }

src/Device/Connection.php

@@ -1,34 +1,58 @@
 <?php
 
+/**
+ * Connection.php
+ *
+ * (c) AMJones <am@jonesiscoding.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
 namespace DevCoding\Device;
 
 use DevCoding\Hints\Hint\ECT;
 use DevCoding\Hints\Hint\RemoteAddr;
 use DevCoding\Hints\Hint\SaveData;
 
 /**
- * Class Connection
- * @package DevCoding\Device
+ * Object class representing the connection of a device.
+ *
+ * @author  AMJones <am@jonesiscoding.com
+ * @license https://github.com/jonesiscoding/code-object/blob/main/LICENSE
  */
 class Connection extends DeviceChild
 {
   /**
-   * @return bool
+   * Returns the Effective Connection type: 4g, 3g, 2g, or slow-2g, as taken from the ECT header, or alternately the
+   * 'ect' key of the device.js cookie.
+   *
+   * @see ECT
+   * @return string
    */
-  public function getEffectiveType()
+  public function getEffectiveType(): string
   {
     return $this->ClientHints->get(ECT::HEADER);
   }
 
   /**
-   * @return string|null
+   * Returns the IP address of the device, or a default value if the IP cannot be found.
+   *
+   * @see RemoteAddr
+   * @return string
    */
-  public function getRemoteAddress()
+  public function getRemoteAddress(): string
   {
     return $this->ClientHints->get(RemoteAddr::HEADER);
   }
 
   /**
+   * Evaluates if the app should attempt to save data in responses to the device.  This can be due to user preference,
+   * connection type, and other aspects of the device connection.
+   *
+   * Value is based on the 'Save-Data' header, the ECT header, and other items in the legacy 'Navigator' javascript API.
+   *
+   * @see SaveData
    * @return bool
    */
   public function isSaveData()

src/Device/Device.php

@@ -1,5 +1,14 @@
 <?php
 
+/**
+ * Device.php
+ *
+ * (c) AMJones <am@jonesiscoding.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
 namespace DevCoding\Device;
 
 use DevCoding\Helper\Dependency\ServiceBag;
@@ -15,11 +24,10 @@
 use DevCoding\Hints\Hint\Width;
 
 /**
- * Device.
+ * Object class representing the device making an HTTP(s) request.
  *
- * Class Device
- *
- * @package DevCoding\Device
+ * @author  AMJones <am@jonesiscoding.com
+ * @license https://github.com/jonesiscoding/code-object/blob/main/LICENSE
  */
 class Device
 {
@@ -52,6 +60,10 @@ public static function create($config = [])
   // region //////////////////////////////////////////////// Hardware Getters
 
   /**
+   * Returns the device model name (if available in the 'Sec-CH-UA-Model' header) else a default value.
+   *
+   * @see Model
+   *
    * @return string|null
    */
   public function getModel()
@@ -60,22 +72,30 @@ public function getModel()
   }
 
   /**
-   * @return float|int
+   * Returns a coarse value reflecting the amount of RAM in Gigabytes available to the device (if available in the
+   * 'Device-Memory' header) else a default value.
+   *
+   * @see DeviceMemory
+   * @return float
    */
   public function getDeviceMemory()
   {
     return $this->getClientHints()->get(DeviceMemory::HEADER);
   }
 
   /**
-   * @return float|int
+   * Returns the DPR of the device (if it can be determined) else a default value.
+   *
+   * @deprecated Use Screen:getDevicePixelRatio
+   * @return float
    */
   public function getDevicePixelRatio()
   {
     return $this->getClientHints()->get(DPR::HEADER);
   }
 
   /**
+   * @deprecated Use Connection::getEffectiveConnectionType
    * @return string
    */
   public function getEffectiveConnectionType()
@@ -84,6 +104,7 @@ public function getEffectiveConnectionType()
   }
 
   /**
+   * @deprecated Use Screen::getHeight
    * @return float|int
    */
   public function getHeight()
@@ -92,6 +113,7 @@ public function getHeight()
   }
 
   /**
+   * @deprecated Use Screen::getWidth
    * @return float|int
    */
   public function getWidth()
@@ -104,33 +126,42 @@ public function getWidth()
   // region //////////////////////////////////////////////// Subset Getters
 
   /**
+   * Returns an object representing the software used on the device.
+   *
    * @return Client
    */
-  public function Client()
+  public function Client(): Client
   {
     return $this->get(Client::class);
   }
 
   /**
+   * Returns an object representing the screen on the device.  For devices with more than one screen, only the screen
+   * containing the client software at the time of the last request is reflected.
+   *
    * @return Screen
    */
-  public function Screen()
+  public function Screen(): Screen
   {
     return $this->get(Screen::class);
   }
 
   /**
+   * Returns an object representing the platform used on the device.
+   *
    * @return Platform
    */
-  public function Platform()
+  public function Platform(): Platform
   {
     return $this->get(Platform::class);
   }
 
   /**
+   * Returns an object representing the preferences of the user using the device.
+   *
    * @return Preferences
    */
-  public function Preferences()
+  public function Preferences(): Preferences
   {
     return $this->get(Preferences::class);
   }
@@ -173,7 +204,7 @@ public function isSunset(): bool
    *
    * @return bool
    */
-  public function isPolyfill()
+  public function isPolyfill(): bool
   {
     $ConfigBag = $this->container->get(ConfigBag::class);
     $required  = $ConfigBag->getRequire();
@@ -200,7 +231,9 @@ public function isPolyfill()
   // region //////////////////////////////////////////////// Helper Methods
 
   /**
-   * @param $id
+   * Returns a service from the service container, instantiating that service as needed.
+   *
+   * @param string $id The fully qualified class name of the service object.
    *
    * @return mixed|object
    */
@@ -210,9 +243,12 @@ protected function get($id)
   }
 
   /**
+   * Returns the ClientHints object.  If that object is not present in the service container, it will be created
+   * using the configuration given at instantiation of this device.
+   *
    * @return ClientHints
    */
-  public function getClientHints()
+  public function getClientHints(): ClientHints
   {
     if (!$this->container->has(ClientHints::class))
     {
@@ -235,12 +271,14 @@ public function getClientHints()
   }
 
   /**
+   * Evaluates if the device has all the features or hint values given in the 'require' key of the configuration.
+   *
    * @param string $key
    * @param mixed $expected
    *
    * @return bool
    */
-  protected function isValid($key, $expected)
+  protected function isValid($key, $expected): bool
   {
     $ClientHints = $this->getClientHints();
     if ($ClientHints->has($key))

src/Device/DeviceChild.php

@@ -2,8 +2,23 @@
 
 namespace DevCoding\Device;
 
+/**
+ * DeviceChild.php
+ *
+ * (c) AMJones <am@jonesiscoding.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
 use DevCoding\Hints\ClientHints;
 
+/**
+ * Base class for objects that are children of the device object, allowing access to the ClientHints property.
+ *
+ * @author  AMJones <am@jonesiscoding.com
+ * @license https://github.com/jonesiscoding/code-object/blob/main/LICENSE
+ */
 abstract class DeviceChild
 {
   /** @var ClientHints */