merged branch drak/docblocks (PR #2546)

Commits
-------

09e1e60 Grammar changes.
b4d0f4b Grammar changes
a0e62f0 Fix typos.
e6627fb Docblocks.

Discussion
----------

[HttpFoundation] Docblocks.

Bug fix: no
Feature addition: no
Backwards compatibility break: no
Symfony2 tests pass: n/a
Fixes the following tickets: -

Added missing docblocks and type hints.  Improves use with IDE and auto-generated API docs.

src/Symfony/Component/HttpFoundation/ParameterBag.php

@@ -20,6 +20,11 @@ namespace Symfony\Component\HttpFoundation;
  */
 class ParameterBag
 {
+    /**
+     * Parameter storage.
+     * 
+     * @var array
+     */
     protected $parameters;
 
     /**

src/Symfony/Component/HttpFoundation/Request.php

@@ -71,20 +71,74 @@ class Request
      */
     public $headers;
 
+    /**
+     * @var string
+     */
     protected $content;
+    
+    /**
+     * @var string
+     */
     protected $languages;
+    
+    /**
+     * @var string
+     */
     protected $charsets;
+    
+    /**
+     * @var string
+     */
     protected $acceptableContentTypes;
+    
+    /**
+     * @var string
+     */
     protected $pathInfo;
+    
+    /**
+     * @var string
+     */
     protected $requestUri;
+    
+    /**
+     * @var string
+     */
     protected $baseUrl;
+    
+    /**
+     * @var string
+     */
     protected $basePath;
+    
+    /**
+     * @var string
+     */
     protected $method;
+    
+    /**
+     * @var string
+     */
     protected $format;
+    
+    /**
+     * @var \Symfony\Component\HttpFoundation\Session
+     */
     protected $session;
+    
+    /**
+     * @var string
+     */
     protected $locale;
+    
+    /**
+     * @var string
+     */
     protected $defaultLocale = 'en';
 
+    /**
+     * @var string
+     */
     static protected $formats;
 
     /**
@@ -894,16 +948,35 @@ class Request
         $this->format = $format;
     }
 
+    /**
+     * Sets the default locale.
+     * 
+     * @param string $locale 
+     * 
+     * @api
+     */
     public function setDefaultLocale($locale)
     {
         $this->setPhpDefaultLocale($this->defaultLocale = $locale);
     }
 
+    /**
+     * Sets the locale.
+     * 
+     * @param string $locale 
+     * 
+     * @api
+     */
     public function setLocale($locale)
     {
         $this->setPhpDefaultLocale($this->locale = $locale);
     }
 
+    /**
+     * Get the locale.
+     * 
+     * @return string
+     */
     public function getLocale()
     {
         return null === $this->locale ? $this->defaultLocale : $this->locale;
@@ -1145,6 +1218,11 @@ class Request
         return $requestUri;
     }
 
+    /**
+     * Prepares the base URL.
+     * 
+     * @return string 
+     */
     protected function prepareBaseUrl()
     {
         $filename = basename($this->server->get('SCRIPT_FILENAME'));
@@ -1207,7 +1285,7 @@ class Request
     }
 
     /**
-     * Prepares base path.
+     * Prepares the base path.
      *
      * @return string base path
      */
@@ -1233,7 +1311,7 @@ class Request
     }
 
     /**
-     * Prepares path info.
+     * Prepares the path info.
      *
      * @return string path info
      */
@@ -1280,6 +1358,11 @@ class Request
         );
     }
 
+    /**
+     * Sets the default PHP locale.
+     * 
+     * @param string $locale 
+     */
     private function setPhpDefaultLocale($locale)
     {
         // if either the class Locale doesn't exist, or an exception is thrown when

src/Symfony/Component/HttpFoundation/RequestMatcher.php

@@ -20,10 +20,31 @@ namespace Symfony\Component\HttpFoundation;
  */
 class RequestMatcher implements RequestMatcherInterface
 {
+    /**
+     * @var string
+     */
     private $path;
+    
+    /**
+     * @var string
+     */
     private $host;
+    
+    /**
+     * @var string
+     */
     private $methods;
+    
+    /**
+     * @var string 
+     */
     private $ip;
+    
+    /**
+     * Attributes.
+     * 
+     * @var array 
+     */
     private $attributes;
 
     public function __construct($path = null, $host = null, $methods = null, $ip = null, array $attributes = array())
@@ -122,6 +143,14 @@ class RequestMatcher implements RequestMatcherInterface
         return true;
     }
 
+    /**
+     * Validates an IP address.
+     * 
+     * @param string $requestIp
+     * @param string $ip
+     * 
+     * @return boolean True valid, false if not.
+     */
     protected function checkIp($requestIp, $ip)
     {
         // IPv6 address
@@ -132,6 +161,14 @@ class RequestMatcher implements RequestMatcherInterface
         }
     }
 
+    /**
+     * Validates an IPv4 address.
+     * 
+     * @param string $requestIp
+     * @param string $ip
+     * 
+     * @return boolean True valid, false if not.
+     */
     protected function checkIp4($requestIp, $ip)
     {
         if (false !== strpos($ip, '/')) {
@@ -149,8 +186,15 @@ class RequestMatcher implements RequestMatcherInterface
     }
 
     /**
+     * Validates an IPv6 address.
+     * 
      * @author David Soria Parra <dsp at php dot net>
      * @see https://github.com/dsp/v6tools
+     * 
+     * @param string $requestIp
+     * @param string $ip
+     * 
+     * @return boolean True valid, false if not.
      */
     protected function checkIp6($requestIp, $ip)
     {

src/Symfony/Component/HttpFoundation/Response.php

@@ -25,12 +25,36 @@ class Response
      */
     public $headers;
 
+    /**
+     * @var string
+     */
     protected $content;
+    
+    /**
+     * @var string
+     */
     protected $version;
+    
+    /**
+     * @var integer
+     */
     protected $statusCode;
+    
+    /**
+     * @var string
+     */
     protected $statusText;
+    
+    /**
+     * @var string
+     */
     protected $charset;
 
+    /**
+     * Status codes translation table.
+     *
+     * @var array
+     */
     static public $statusTexts = array(
         100 => 'Continue',
         101 => 'Switching Protocols',
@@ -826,6 +850,10 @@ class Response
 
     // http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
     /**
+     * Is response invalid?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isInvalid()
@@ -834,6 +862,10 @@ class Response
     }
 
     /**
+     * Is response informative?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isInformational()
@@ -842,6 +874,10 @@ class Response
     }
 
     /**
+     * Is response successful?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isSuccessful()
@@ -850,6 +886,10 @@ class Response
     }
 
     /**
+     * Is the response a redirect?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isRedirection()
@@ -858,6 +898,10 @@ class Response
     }
 
     /**
+     * Is there a client error?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isClientError()
@@ -866,6 +910,10 @@ class Response
     }
 
     /**
+     * Was there a server side error?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isServerError()
@@ -874,6 +922,10 @@ class Response
     }
 
     /**
+     * Is the response OK?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isOk()
@@ -882,6 +934,10 @@ class Response
     }
 
     /**
+     * Is the reponse forbidden?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isForbidden()
@@ -890,6 +946,10 @@ class Response
     }
 
     /**
+     * Is the response a not found error?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isNotFound()
@@ -898,6 +958,10 @@ class Response
     }
 
     /**
+     * Is the response a redirect of some form?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isRedirect($location = null)
@@ -906,10 +970,14 @@ class Response
     }
 
     /**
+     * Is the response empty?
+     * 
+     * @return boolean
+     * 
      * @api
      */
     public function isEmpty()
     {
         return in_array($this->statusCode, array(201, 204, 304));
     }
-}
+}

src/Symfony/Component/HttpFoundation/ResponseHeaderBag.php

@@ -26,7 +26,14 @@ class ResponseHeaderBag extends HeaderBag
     const DISPOSITION_ATTACHMENT = 'attachment';
     const DISPOSITION_INLINE     = 'inline';
 
+    /**
+     * @var array
+     */
     protected $computedCacheControl = array();
+    
+    /**
+     * @var array
+     */
     protected $cookies              = array();
 
     /**

src/Symfony/Component/HttpFoundation/ServerBag.php

@@ -19,6 +19,11 @@ namespace Symfony\Component\HttpFoundation;
  */
 class ServerBag extends ParameterBag
 {
+    /**
+     * Gets the HTTP headers.
+     * 
+     * @return string 
+     */
     public function getHeaders()
     {
         $headers = array();

src/Symfony/Component/HttpFoundation/SessionStorage/ArraySessionStorage.php

@@ -22,13 +22,24 @@ namespace Symfony\Component\HttpFoundation\SessionStorage;
 
 class ArraySessionStorage implements SessionStorageInterface
 {
+    /**
+     * Storage data.
+     * 
+     * @var array
+     */
     private $data = array();
 
+    /**
+     * {@inheritdoc}
+     */
     public function read($key, $default = null)
     {
         return array_key_exists($key, $this->data) ? $this->data[$key] : $default;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function regenerate($destroy = false)
     {
         if ($destroy) {
@@ -38,19 +49,31 @@ class ArraySessionStorage implements SessionStorageInterface
         return true;
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function remove($key)
     {
         unset($this->data[$key]);
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function start()
     {
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function getId()
     {
     }
 
+    /**
+     * {@inheritdoc}
+     */
     public function write($key, $data)
     {
         $this->data[$key] = $data;

src/Symfony/Component/HttpFoundation/SessionStorage/FilesystemSessionStorage.php

@@ -23,8 +23,25 @@ namespace Symfony\Component\HttpFoundation\SessionStorage;
  */
 class FilesystemSessionStorage extends NativeSessionStorage
 {
+    /**
+     * File path.
+     * 
+     * @var string
+     */
     private $path;
+    
+    /**
+     * Data.
+     * 
+     * @var array
+     */
     private $data;
+    
+    /**
+     * Session started flag.
+     * 
+     * @var boolean
+     */
     private $started;
 
     /**

src/Symfony/Component/HttpFoundation/SessionStorage/PdoSessionStorage.php

@@ -19,7 +19,18 @@ namespace Symfony\Component\HttpFoundation\SessionStorage;
  */
 class PdoSessionStorage extends NativeSessionStorage
 {
+    /**
+     * PDO instance.
+     * 
+     * @var \PDO
+     */
     private $db;
+    
+    /**
+     * Database options.
+     * 
+     * @var array
+     */
     private $dbOptions;
 
     /**
@@ -242,6 +253,8 @@ class PdoSessionStorage extends NativeSessionStorage
      *
      * @param string $id
      * @param string $data
+     * 
+     * @return boolean True.
      */
     private function createNewSession($id, $data = '')
     {
@@ -263,4 +276,4 @@ class PdoSessionStorage extends NativeSessionStorage
 
         return true;
     }
-}
+}