@@ -36,9 +36,14 @@ public function initialize(ExecutionContextInterface $context)
3636 /**
3737 * Returns a string representation of the type of the value.
3838 *
39- * @param mixed $value
39+ * This method should be used if you pass the type of a value as
40+ * message parameter to a constraint violation. Note that such
41+ * parameters should usually not be included in messages aimed at
42+ * non-technical people.
4043 *
41- * @return string
44+ * @param mixed $value The value to return the type of
45+ *
46+ * @return string The type of the value
4247 */
4348 protected function formatTypeOf ($ value
4449 {
@@ -48,10 +53,24 @@ protected function formatTypeOf($value)
4853 /**
4954 * Returns a string representation of the value.
5055 *
51- * @param mixed $value
52- * @param bool $prettyDateTime
56+ * This method returns the equivalent PHP tokens for most scalar types
57+ * (i.e. "false" for false, "1" for 1 etc.). Strings are always wrapped
58+ * in double quotes ("). Objects, arrays and resources are formatted as
59+ * "object", "array" and "resource". If the parameter $prettyDateTime
60+ * is set to true, {@link \DateTime} objects will be formatted as
61+ * RFC-3339 dates ("Y-m-d H:i:s").
62+ *
63+ * Be careful when passing message parameters to a constraint violation
64+ * that (may) contain objects, arrays or resources. These parameters
65+ * should only be displayed for technical users. Non-technical users
66+ * won't know what an "object", "array" or "resource" is and will be
67+ * confused by the violation message.
68+ *
69+ * @param mixed $value The value to format as string
70+ * @param bool $prettyDateTime Whether to format {@link \DateTime}
71+ * objects as RFC-3339 dates ("Y-m-d H:i:s")
5372 *
54- * @return string
73+ * @return string The string representation of the passed value
5574 */
5675 protected function formatValue ($ value$ prettyDateTimefalse )
5776 {
@@ -100,10 +119,16 @@ protected function formatValue($value, $prettyDateTime = false)
100119 /**
101120 * Returns a string representation of a list of values.
102121 *
103- * @param array $values
104- * @param bool $prettyDateTime
122+ * Each of the values is converted to a string using
123+ * {@link formatValue()}. The values are then concatenated with commas.
124+ *
125+ * @param array $values A list of values
126+ * @param bool $prettyDateTime Whether to format {@link \DateTime}
127+ * objects as RFC-3339 dates ("Y-m-d H:i:s")
128+ *
129+ * @return string The string representation of the value list
105130 *
106- * @return string
131+ * @see formatValue()
107132 */
108133 protected function formatValues (array $ values$ prettyDateTimefalse )
109134 {
0 commit comments