From a9d113742345fb565b9d818c6a50dabd86f134a9 Mon Sep 17 00:00:00 2001
From: Evan Mattson <me@aaemnnost.tv>
Date: Tue, 21 Jun 2016 17:10:37 +0400
Subject: [PATCH] docblocks

[skip ci]
---
 src/Event/Hook.php                            | 80 ++++++++++++-------
 src/Exception/WP_ErrorException.php           |  5 ++
 src/Meta/Meta.php                             | 41 +++++++---
 .../ModelPostTypeMismatchException.php        | 14 ++++
 src/Post/PostType.php                         | 16 ++--
 src/Support/Callback.php                      |  4 +
 src/Support/Shortcode.php                     | 27 +++++--
 7 files changed, 133 insertions(+), 54 deletions(-)

diff --git a/src/Event/Hook.php b/src/Event/Hook.php
index 6447b18..2c28a0d 100644
--- a/src/Event/Hook.php
+++ b/src/Event/Hook.php
@@ -6,23 +6,42 @@
 
 class Hook
 {
+    /**
+     * The action or filter handle attached to.
+     * @var string
+     */
     protected $handle;
-
+    /**
+     * The callback object holding the target callable.
+     * @var Callback
+     */
     protected $callback;
-
+    /**
+     * The number of parameters defined in the callback's signature.
+     * @var int
+     */
     protected $callbackParamCount;
-
+    /**
+     * The action or filter priority the callback is registered on.
+     * @var mixed
+     */
     protected $priority;
-
+    /**
+     * The number of times the callback has been invoked.
+     * @var int
+     */
     protected $iterations;
-
+    /**
+     * The maximum number of iterations allowed for the callback to be invoked.
+     * @var int
+     */
     protected $maxIterations;
 
 
     /**
-     * Create a new Hook instance
+     * Create a new Hook instance.
      *
-     * @param  string $handle action or filter handle
+     * @param  string $handle   Action or filter handle
      * @param  int    $priority
      *
      * @return static
@@ -33,9 +52,9 @@ public static function on($handle, $priority = 10)
     }
 
     /**
-     * Create a new Hook instance
+     * Create a new Hook instance.
      *
-     * @param  string $handle action or filter handle
+     * @param  string $handle   Action or filter handle
      * @param  int    $priority
      */
     public function __construct($handle, $priority = 10)
@@ -45,9 +64,9 @@ public function __construct($handle, $priority = 10)
     }
 
     /**
-     * Set the callback to be invoked by the action or filter
+     * Set the callback to be invoked by the action or filter.
      *
-     * @param callable $callback
+     * @param callable $callback    The callback to be invoked
      *
      * @return $this
      */
@@ -60,7 +79,7 @@ public function setCallback(callable $callback)
     }
 
     /**
-     * Set the hook in WordPress
+     * Set the hook in WordPress.
      *
      * Both actions and filters are registered as filters.
      *
@@ -74,7 +93,7 @@ public function listen()
     }
 
     /**
-     * Unset the hook in WordPress
+     * Unset the hook in WordPress.
      *
      * @return $this
      */
@@ -86,9 +105,12 @@ public function remove()
     }
 
     /**
-     * Control invocation of the callback
+     * Control invocation of the callback.
+     *
+     * @param $given  The first argument passed to the callback.
+     *                Needed to return for filters.
      *
-     * @return mixed  callback returned value
+     * @return mixed  Returned value from Callback
      */
     public function mediateCallback($given = null)
     {
@@ -100,13 +122,13 @@ public function mediateCallback($given = null)
     }
 
     /**
-     * Whether or not the callback should be invoked
+     * Whether or not the callback should be invoked.
      *
-     * @param  array  $args  all arguments passed to the callback
+     * @param  array  $arguments  All arguments passed to the callback
      *
      * @return bool
      */
-    public function shouldInvoke(array $args)
+    public function shouldInvoke(array $arguments)
     {
         if ($this->hasExceededIterations()) {
             return false;
@@ -116,11 +138,11 @@ public function shouldInvoke(array $args)
     }
 
     /**
-     * Call the callback
+     * Call the callback.
      *
-     * @param  array $arguments  the arguments expected by the callback
+     * @param  array $arguments  All arguments passed to the callback
      *
-     * @return mixed  returned output from the callback
+     * @return mixed  The value returned from the callback
      */
     protected function invokeCallback($arguments)
     {
@@ -132,7 +154,7 @@ protected function invokeCallback($arguments)
     }
 
     /**
-     * Set the callback to only be invoked one time
+     * Set the callback to only be invokable one time.
      *
      * @return $this
      */
@@ -144,9 +166,9 @@ public function once()
     }
 
     /**
-     * Set the callback to only be invoked the given number of times
+     * Set the maximum number of callback invocations to allow.
      *
-     * @param  int $times  maimum iterations of invocations to allow
+     * @param  int $times  The maximum iterations of invocations to allow
      *
      * @return $this
      */
@@ -158,7 +180,7 @@ public function onlyXtimes($times)
     }
 
     /**
-     * Prevent the callback from being triggered again
+     * Prevent the callback from being triggered again.
      *
      * @return $this
      */
@@ -170,9 +192,9 @@ public function bypass()
     }
 
     /**
-     * Set the priority the callback should be registered with
+     * Set the priority the callback should be registered with.
      *
-     * @param  string|int $priority
+     * @param  mixed $priority  The callback priority
      *
      * @return $this
      */
@@ -188,9 +210,9 @@ public function withPriority($priority)
     }
 
     /**
-     * Whether or not the callback has reached the limit of allowed invocations
+     * Whether or not the callback has reached the limit of allowed invocations.
      *
-     * @return boolean  true for limit reached, otherwise false
+     * @return boolean  true for limit reached/exceeded, otherwise false
      */
     protected function hasExceededIterations()
     {
diff --git a/src/Exception/WP_ErrorException.php b/src/Exception/WP_ErrorException.php
index 52e3b86..a784bed 100644
--- a/src/Exception/WP_ErrorException.php
+++ b/src/Exception/WP_ErrorException.php
@@ -6,6 +6,11 @@
 
 class WP_ErrorException extends \RuntimeException
 {
+    /**
+     * WP_ErrorException Constructor.
+     *
+     * @param WP_Error $error  The error to set the message from
+     */
     public function __construct(WP_Error $error)
     {
         $this->message = $error->get_error_message();
diff --git a/src/Meta/Meta.php b/src/Meta/Meta.php
index 4c13543..bfda70c 100644
--- a/src/Meta/Meta.php
+++ b/src/Meta/Meta.php
@@ -11,12 +11,20 @@ class Meta
      * @var string
      */
     protected $type;
-
+    /**
+     * The object ID this metadata is for
+     * @var int
+     */
     protected $object_id;
-
+    /**
+     * The key the metadata is for
+     * @var string
+     */
     protected $key;
 
     /**
+     * Meta Constructor.
+     *
      * @param string     $type      Meta type
      * @param int|string $object_id ID of the object metadata is for
      * @param string     $key       Meta key
@@ -24,12 +32,12 @@ class Meta
     public function __construct($type, $object_id, $key)
     {
         $this->type      = $type;
-        $this->object_id = $object_id;
+        $this->object_id = (int) $object_id;
         $this->key       = $key;
     }
 
     /**
-     * Get the single meta data
+     * Get the single meta data.
      *
      * @return mixed
      */
@@ -39,7 +47,7 @@ public function get()
     }
 
     /**
-     * Get all meta data
+     * Get all meta data.
      *
      * @return Collection
      */
@@ -49,7 +57,7 @@ public function all()
     }
 
     /**
-     * Set the meta value
+     * Set the meta value.
      *
      * @param mixed  $value
      * @param string $prev_value
@@ -62,10 +70,12 @@ public function set($value, $prev_value = '')
     }
 
     /**
-     * Add metadata for the specified object
+     * Add metadata for the specified object.
      *
      * @param mixed  $value  The value to add
-     * @param bool $unique
+     * @param bool $unique  Whether the specified metadata key should be unique
+     *                      for the object.  If true, and the object already has
+     *                      a value for the specified metadata key, no change will be made.
      *
      * @return int|false The meta ID on success, false on failure.
      */
@@ -93,7 +103,7 @@ public function delete($value = '')
     }
 
     /**
-     * Determine if a meta key is set for a given object
+     * Determine if a meta key is set for a given object.
      *
      * @return bool     True of the key is set, false if not.
      */
@@ -103,9 +113,9 @@ public function exists()
     }
 
     /**
-     * Get the object_id
+     * Get the object_id.
      *
-     * @return int|string
+     * @return int  Object ID
      */
     public function getObjectId()
     {
@@ -113,13 +123,22 @@ public function getObjectId()
     }
 
     /**
+     * Magic getter.
+     *
+     * @param string $property  The called unaccessible property name
      *
+     * @return mixed
      */
     public function __get($property)
     {
         return $this->get($property);
     }
 
+    /**
+     * Get the string representation of the meta data.
+     *
+     * @return string  The meta value
+     */
     public function __toString()
     {
         return $this->get();
diff --git a/src/Post/Exception/ModelPostTypeMismatchException.php b/src/Post/Exception/ModelPostTypeMismatchException.php
index a853583..969478a 100644
--- a/src/Post/Exception/ModelPostTypeMismatchException.php
+++ b/src/Post/Exception/ModelPostTypeMismatchException.php
@@ -9,9 +9,23 @@ class ModelPostTypeMismatchException extends \RuntimeException
 {
     const MESSAGE_FORMAT = '{modelClass} instantiated with post of type "{givenPostType}", but requires a post of type "{modelPostType}".';
 
+    /**
+     * The model's full class name
+     * @var string
+     */
     protected $modelClass;
+    /**
+     * The post object
+     * @var WP_Post
+     */
     protected $post;
 
+    /**
+     * ModelPostTypeMismatchException Constructor.
+     *
+     * @param string  $modelClass  The model's full class name
+     * @param WP_Post $post        The post object
+     */
     public function __construct($modelClass, WP_Post $post)
     {
         $this->modelClass = $modelClass;
diff --git a/src/Post/PostType.php b/src/Post/PostType.php
index 604413b..517b481 100644
--- a/src/Post/PostType.php
+++ b/src/Post/PostType.php
@@ -26,7 +26,7 @@ class PostType
     /**
      * PostType Constructor
      *
-     * @param object post type object
+     * @param stdClass $object  The WordPress post type object
      */
     public function __construct(stdClass $object)
     {
@@ -38,10 +38,10 @@ public function __construct(stdClass $object)
      *
      * Loads an existing type, or returns a new builder for registering a new type.
      *
-     * @param  string $slug  string - the post type slug ("name")
+     * @param  string $slug  The post type slug
      *
-     * @return mixed         static - if the post type has been registered
-     *                       PostTypeBuilder otherwise
+     * @return static|PostTypeBuilder  If the post type has been registered, a new static instance is returned.
+     *                                 Otherwise a new PostTypeBuilder is created for building a new post type to register.
      */
     public static function make($slug)
     {
@@ -55,7 +55,7 @@ public static function make($slug)
     /**
      * Create a new instance from an existing type.
      *
-     * @param  string $slug  post type id  (slug/name)
+     * @param  string $slug  The post type slug
      *
      * @return static
      */
@@ -71,6 +71,8 @@ public static function load($slug)
     /**
      * Checks if a post type with this slug has been registered.
      *
+     * @param string $slug  The post type slug
+     *
      * @return bool
      */
     public static function exists($slug)
@@ -91,8 +93,8 @@ public function object()
     /**
      * Check for feature support.
      *
-     * @param mixed $features  string - feature
-     *                         array - many features
+     * @param string,...|array $features  string - First feature of possible many,
+     *                                    array - Many features to check support for.
      *
      * @return mixed
      */
diff --git a/src/Support/Callback.php b/src/Support/Callback.php
index 091962c..d0e6eaf 100644
--- a/src/Support/Callback.php
+++ b/src/Support/Callback.php
@@ -4,6 +4,10 @@
 
 class Callback
 {
+    /**
+     * The normalized callable.
+     * @var mixed
+     */
     protected $target;
 
     /**
diff --git a/src/Support/Shortcode.php b/src/Support/Shortcode.php
index 8de6f37..5458da7 100644
--- a/src/Support/Shortcode.php
+++ b/src/Support/Shortcode.php
@@ -22,6 +22,13 @@ abstract class Shortcode
      */
     protected $tag;
 
+    /**
+     * Shortcode Constructor.
+     *
+     * @param array $atts      Shortcode attributes
+     * @param string $content  The inner (enclosed) content
+     * @param string $tag      The called shortcode tag
+     */
     public function __construct($atts, $content, $tag)
     {
         $this->attributes = $atts;
@@ -30,9 +37,9 @@ public function __construct($atts, $content, $tag)
     }
 
     /**
-     * Register a tag for this shortcode
+     * Register a tag for this shortcode.
      *
-     * @param  mixed $tag  the tag to register with the shortcode
+     * @param mixed $tag  The tag to register with this shortcode class
      */
     public static function register($tag)
     {
@@ -41,6 +48,12 @@ public static function register($tag)
 
     /**
      * WordPress Shortcode Callback
+     *
+     * @param  mixed $atts      Shortcode attributes
+     * @param  string $content  The inner (enclosed) content
+     * @param  string $tag      The called shortcode tag
+     *
+     * @return static
      */
     public static function controller($atts, $content, $tag)
     {
@@ -48,9 +61,9 @@ public static function controller($atts, $content, $tag)
     }
 
     /**
-    * Render the shortcode to string
+    * Call the shortcode's handler and return the output.
     *
-    * @return string
+    * @return mixed  Rendered shortcode output
     */
     public function render()
     {
@@ -64,7 +77,7 @@ public function render()
     }
 
     /**
-     * Catch-all render method
+     * Catch-all render method.
      *
      * @return string
      */
@@ -74,9 +87,9 @@ protected function handler()
     }
 
     /**
-     * Get all attributes as a collection
+     * Get all attributes as a collection.
      *
-     * @return \Illuminate\Support\Collection
+     * @return Collection
      */
     public function attributes()
     {