merged branch umpirsky/request-doc-fix (PR #1328)

Commits
-------

cbd1dfd Minor doc fixes in Request.

Discussion
----------

Minor doc fixes in Request.

Minor fix, contribution warmup :)

src/Symfony/Component/HttpFoundation/Request.php

@@ -321,14 +321,27 @@ class Request
         $_REQUEST = array_merge($_GET, $_POST);
     }
 
-    // Order of precedence: GET, PATH, POST, COOKIE
-    // Avoid using this method in controllers:
-    //  * slow
-    //  * prefer to get from a "named" source
-    // This method is mainly useful for libraries that want to provide some flexibility
+    /**
+     * This method is mainly useful for libraries that want to provide some flexibility.
+     * 
+     * Order of precedence: GET, PATH, POST, COOKIE
+     * Avoid using this method in controllers:
+     *  * slow
+     *  * prefer to get from a "named" source
+     * 
+     * @param string    $key        the key
+     * @param mixed     $default    the default value
+     * @param type      $deep       is parameter deep in multidimensional array
+     * 
+     * @return mixed
+     */
     public function get($key, $default = null, $deep = false)
     {
-        return $this->query->get($key, $this->attributes->get($key, $this->request->get($key, $default, $deep), $deep), $deep);
+        return $this->query->get(
+            $key, 
+            $this->attributes->get($key, $this->request->get($key, $default, $deep), $deep), 
+            $deep
+        );
     }
 
     /**
@@ -1018,6 +1031,11 @@ class Request
         return rtrim($baseUrl, '/');
     }
 
+    /*
+     * Prepare base path.
+     * 
+     * @return string base path
+     */
     protected function prepareBasePath()
     {
         $filename = basename($this->server->get('SCRIPT_FILENAME'));
@@ -1039,6 +1057,11 @@ class Request
         return rtrim($basePath, '/');
     }
 
+    /**
+     * Prepare path info.
+     *
+     * @return string path info
+     */
     protected function preparePathInfo()
     {
         $baseUrl = $this->getBaseUrl();
@@ -1064,6 +1087,9 @@ class Request
         return (string) $pathInfo;
     }
 
+    /**
+     * Initialize HTTP request formats.
+     */
     static protected function initializeFormats()
     {
         static::$formats = array(