[WIP] Improved PHPDoc comments

src/JsonSchema/Constraints/BaseConstraint.php

@@ -17,34 +17,51 @@
 use JsonSchema\Validator;
 
 /**
- * A more basic constraint definition - used for the public
- * interface to avoid exposing library internals.
+ * The base constraint definition from which all other constraint classes descend
+ *
+ * This class is also used as the base class for Validator, in order to expose some
+ * common functionality to end users of the library.
+ *
+ * @package justinrainbow/json-schema
+ *
+ * @license MIT
  */
 class BaseConstraint
 {
     /**
-     * @var array Errors
+     * @var array List of errors encountered during validation against the current constraint
      */
     protected $errors = array();
 
     /**
-     * @var int All error types which have occurred
+     * @var int Bitwise list of all error categories in which a validation error has occurred
      */
     protected $errorMask = Validator::ERROR_NONE;
 
     /**
-     * @var Factory
+     * @var Factory Factory object containing global state, config options & misc functionality
      */
     protected $factory;
 
     /**
-     * @param Factory $factory
+     * Create a new constraint instance
+     *
+     * @api via JsonSchema\Validator
+     *
+     * @param Factory $factory Factory object containing global state, config options & misc functionality
      */
     public function __construct(Factory $factory = null)
     {
         $this->factory = $factory ?: new Factory();
     }
 
+    /**
+     * Add an error to the list of errors encountered during validation
+     *
+     * @param ConstraintError $constraint Which error condition has been encountered
+     * @param JsonPointer     $path       Where the error occurred
+     * @param array           $more       List of additional parameters used to generate error messages
+     */
     public function addError(ConstraintError $constraint, JsonPointer $path = null, array $more = array())
     {
         $message = $constraint ? $constraint->getMessage() : '';
@@ -74,6 +91,11 @@ public function addError(ConstraintError $constraint, JsonPointer $path = null,
         $this->errorMask |= $error['context'];
     }
 
+    /**
+     * Add multiple, already-rendered errors to the current list for this constraint
+     *
+     * @param array $errors List of errors to add
+     */
     public function addErrors(array $errors)
     {
         if ($errors) {
@@ -87,6 +109,18 @@ public function addErrors(array $errors)
         }
     }
 
+    /**
+     * Get a list of all errors encountered during validation.
+     *
+     * If you only want to return errors in particular categories, set $errorContext to
+     * include the desired categories.
+     *
+     * @api via JsonSchema\Validator
+     *
+     * @param int $errorContext Which categories of error to include
+     *
+     * @return array List of errors
+     */
     public function getErrors($errorContext = Validator::ERROR_ALL)
     {
         if ($errorContext === Validator::ERROR_ALL) {
@@ -100,6 +134,18 @@ public function getErrors($errorContext = Validator::ERROR_ALL)
         });
     }
 
+    /**
+     * Return the number of errors encountered during validation.
+     *
+     * If you only want to count the errors in particular categories, set $errorContext to
+     * include the desired categories.
+     *
+     * @api via JsonSchema\Validator
+     *
+     * @param int $errorContext Which categories of error to include
+     *
+     * @return int Number of errors
+     */
     public function numErrors($errorContext = Validator::ERROR_ALL)
     {
         if ($errorContext === Validator::ERROR_ALL) {
@@ -109,14 +155,22 @@ public function numErrors($errorContext = Validator::ERROR_ALL)
         return count($this->getErrors($errorContext));
     }
 
+    /**
+     * Check whether the most recent validation attempt completed successfully
+     *
+     * @api via JsonSchema\Validator
+     *
+     * @return bool True if no errors were encountered, false otherwise
+     */
     public function isValid()
     {
         return !$this->getErrors();
     }
 
     /**
-     * Clears any reported errors.  Should be used between
-     * multiple validation checks.
+     * Clear the list of reported errors. Should be used between multiple validation attempts.
+     *
+     * reset() is called automatically when using JsonSchema\Validator::validate().
      */
     public function reset()
     {
@@ -125,9 +179,11 @@ public function reset()
     }
 
     /**
-     * Get the error mask
+     * Get a list of categories in which a validation error has occurred
+     *
+     * @api via JsonSchema\Validator
      *
-     * @return int
+     * @return int Bitwise list of error categories that were encountered
      */
     public function getErrorMask()
     {
@@ -137,9 +193,9 @@ public function getErrorMask()
     /**
      * Recursively cast an associative array to an object
      *
-     * @param array $array
+     * @param array $array The array to cast
      *
-     * @return object
+     * @return object The cast object
      */
     public static function arrayToObjectRecursive($array)
     {

src/JsonSchema/Enum.php

@@ -2,6 +2,17 @@
 
 namespace JsonSchema;
 
+/**
+ * Alias class for \MabeEnum\Enum, so that the underlying class can be easily changed or extended.
+ *
+ * This library currently contains no custom functionality, but defines this class so that
+ * the Enum interface can be preserved if the upstream API changes, or a different Enum package
+ * is used.
+ *
+ * @package justinrainbow\json-schema
+ *
+ * @license MIT
+ */
 abstract class Enum extends \MabeEnum\Enum
 {
 }

src/JsonSchema/Rfc3339.php

@@ -2,16 +2,24 @@
 
 namespace JsonSchema;
 
+/**
+ * Helper for creating DateTime objects from an RFC-3339 string
+ *
+ * @package justinrainbow\json-schema
+ *
+ * @license MIT
+ */
 class Rfc3339
 {
+    /** The regular expression used to tokenize the RFC-3339 date-time string */
     const REGEX = '/^(\d{4}-\d{2}-\d{2}[T ]{1}\d{2}:\d{2}:\d{2})(\.\d+)?(Z|([+-]\d{2}):?(\d{2}))$/';
 
     /**
-     * Try creating a DateTime instance
+     * Create a DateTime object based on an RFC-3339 string
      *
-     * @param string $string
+     * @param string $string The string to parse
      *
-     * @return \DateTime|null
+     * @return \DateTime|null A DateTime object corresponding to the given string, or null on error
      */
     public static function createFromString($string)
     {

src/JsonSchema/SchemaStorage.php

@@ -8,14 +8,35 @@
 use JsonSchema\Uri\UriResolver;
 use JsonSchema\Uri\UriRetriever;
 
+/**
+ * Storage schema for user-provided and retrieved schema objects
+ *
+ * @package justinrainbow\json-schema
+ *
+ * @license MIT
+ */
 class SchemaStorage implements SchemaStorageInterface
 {
+    /** URI used for schemas which are provided by the user and have no associated URI */
     const INTERNAL_PROVIDED_SCHEMA_URI = 'internal://provided-schema';
 
+    /** @var UriRetriever UriRetriever instance to use for this SchemaStorage */
     protected $uriRetriever;
+
+    /** @var UriResolver UriResolver instance to use for this SchemaStorage */
     protected $uriResolver;
+
+    /** @var array List of cached schemas */
     protected $schemas = array();
 
+    /**
+     * Create a new SchemaStorage instance
+     *
+     * @api
+     *
+     * @param UriRetriever $uriRetriever UriRetriever instance to use for this SchemaStorage (optional)
+     * @param UriResolver  $uriResolver  UriResolver instance to use for this SchemaStorage (optional)
+     */
     public function __construct(
         UriRetrieverInterface $uriRetriever = null,
         UriResolverInterface $uriResolver = null
@@ -25,6 +46,8 @@ public function __construct(
     }
 
     /**
+     * Get the UriRetriever instance used for this SchemaStorage
+     *
      * @return UriRetrieverInterface
      */
     public function getUriRetriever()
@@ -33,6 +56,8 @@ public function getUriRetriever()
     }
 
     /**
+     * Get the UriResolver instance used for this SchemaStorage
+     *
      * @return UriResolverInterface
      */
     public function getUriResolver()
@@ -41,7 +66,15 @@ public function getUriResolver()
     }
 
     /**
-     * {@inheritdoc}
+     * Add a schema to the cache
+     *
+     * This method can be used to add a user-provided schema object, or if just a URI is provided,
+     * can fetch the schema remotely using the configured UriResolver / UriRetriever objects.
+     *
+     * @api
+     *
+     * @param string $id     The unique identifying URI associated with the schema
+     * @param mixed  $schema The schema definition (optional)
      */
     public function addSchema($id, $schema = null)
     {
@@ -107,7 +140,16 @@ private function expandRefs(&$schema, $base = null)
     }
 
     /**
-     * {@inheritdoc}
+     * Get a decoded schema
+     *
+     * If the schema is present in the cache, it will be returned directly. Otherwise, the library
+     * will fetch it remotely using the configured UriResolver / UriRetriever objects.
+     *
+     * @api
+     *
+     * @param string $id The unique identifying URI associated with the schema
+     *
+     * @return mixed The decoded schema definition
      */
     public function getSchema($id)
     {
@@ -119,7 +161,12 @@ public function getSchema($id)
     }
 
     /**
-     * {@inheritdoc}
+     * Resolve a uri-reference pointer and return the target schema object
+     *
+     * @param string $ref          The reference to resolve
+     * @param array  $resolveStack Internal list of resolved objects (used for loop detection)
+     *
+     * @return mixed The referenced schema object
      */
     public function resolveRef($ref, $resolveStack = array())
     {
@@ -154,7 +201,12 @@ public function resolveRef($ref, $resolveStack = array())
     }
 
     /**
-     * {@inheritdoc}
+     * Check a schema object for $ref, and resolve it if present. Returns the processed schema object.
+     *
+     * @param mixed $refSchema    The schema to check
+     * @param array $resolveStack Internal list of resolved objects (used for loop detection)
+     *
+     * @return mixed The final schema object after all $ref properties have been recursively resolved
      */
     public function resolveRefSchema($refSchema, $resolveStack = array())
     {