[Validator] Added inline documentation for the PropertyPath utility c…

…lass

src/Symfony/Component/Validator/Util/PropertyPath.php

@@ -12,11 +12,29 @@
 namespace Symfony\Component\Validator\Util;
 
 /**
- * @since  %%NextVersion%%
+ * Contains utility methods for dealing with property paths.
+ *
+ * For more extensive functionality, use Symfony's PropertyAccess component.
+ *
+ * @since  2.5
  * @author Bernhard Schussek <bschussek@gmail.com>
  */
 class PropertyPath
 {
+    /**
+     * Appends a path to a given property path.
+     *
+     * If the base path is empty, the appended path will be returned unchanged.
+     * If the base path is not empty, and the appended path starts with a
+     * squared opening bracket ("["), the concatenation of the two paths is
+     * returned. Otherwise, the concatenation of the two paths is returned,
+     * separated by a dot (".").
+     *
+     * @param string $basePath The base path
+     * @param string $subPath  The path to append
+     *
+     * @return string The concatenation of the two property paths
+     */
     public static function append($basePath, $subPath)
     {
         if ('' !== (string) $subPath) {
@@ -30,6 +48,9 @@ public static function append($basePath, $subPath)
         return $basePath;
     }
 
+    /**
+     * Not instantiable.
+     */
     private function __construct()
     {
     }