Merge pull request #9232 from ravage84/3.x-typeinterface-apidocs

Improve API documentation for TypeInterface

src/Database/TypeInterface.php

@@ -15,43 +15,43 @@
 namespace Cake\Database;
 
 /**
- * Encapsulates all conversion functions for values coming from database into PHP and
- * going from PHP into database.
+ * Encapsulates all conversion functions for values coming from a database into PHP and
+ * going from PHP into a database.
  */
 interface TypeInterface
 {
 
     /**
-     * Casts given value from a PHP type to one acceptable by database
+     * Casts given value from a PHP type to one acceptable by a database.
      *
-     * @param mixed $value value to be converted to database equivalent
-     * @param \Cake\Database\Driver $driver object from which database preferences and configuration will be extracted
-     * @return mixed
+     * @param mixed $value Value to be converted to a database equivalent.
+     * @param \Cake\Database\Driver $driver Object from which database preferences and configuration will be extracted.
+     * @return mixed Given PHP type casted to one acceptable by a database.
      */
     public function toDatabase($value, Driver $driver);
 
     /**
-     * Casts given value from a database type to PHP equivalent
+     * Casts given value from a database type to a PHP equivalent.
      *
-     * @param mixed $value value to be converted to PHP equivalent
-     * @param \Cake\Database\Driver $driver object from which database preferences and configuration will be extracted
-     * @return mixed
+     * @param mixed $value Value to be converted to PHP equivalent
+     * @param \Cake\Database\Driver $driver Object from which database preferences and configuration will be extracted
+     * @return mixed Given value casted from a database to a PHP equivalent.
      */
     public function toPHP($value, Driver $driver);
 
     /**
-     * Casts given value to Statement equivalent
+     * Casts given value to its Statement equivalent.
      *
-     * @param mixed $value value to be converted to PDO statement
-     * @param \Cake\Database\Driver $driver object from which database preferences and configuration will be extracted
-     * @return mixed
+     * @param mixed $value Value to be converted to PDO statement.
+     * @param \Cake\Database\Driver $driver Object from which database preferences and configuration will be extracted.
+     * @return mixed Given value casted to its Statement equivalent.
      */
     public function toStatement($value, Driver $driver);
 
     /**
      * Marshalls flat data into PHP objects.
      *
-     * Most useful for converting request data into PHP objects
+     * Most useful for converting request data into PHP objects,
      * that make sense for the rest of the ORM/Database layers.
      *
      * @param mixed $value The value to convert.
@@ -61,18 +61,19 @@ interface TypeInterface
 
     /**
      * Returns the base type name that this class is inheriting.
-     * This is useful when extending base type for adding extra functionality
+     * 
+     * This is useful when extending base type for adding extra functionality,
      * but still want the rest of the framework to use the same assumptions it would
      * do about the base type it inherits from.
      *
-     * @return string
+     * @return string The base type name that this class is inheriting.
      */
     public function getBaseType();
 
     /**
-     * Returns type identifier name for this object
+     * Returns type identifier name for this object.
      *
-     * @return string
+     * @return string The type identifier name for this object.
      */
     public function getName();