Update HTTP documentation

sdk/lib/io/http.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * HTTP status codes.
  */
 abstract class HttpStatus {
@@ skipping 906 matching lines @@
    * To reconstruct the scheme, first 'X-Forwarded-Proto' is checked, and then
    * falling back to server type.
    *
    * To reconstruct the host, fisrt 'X-Forwarded-Host' is checked, then 'Host'
    * and finally calling back to server.
    */
   Uri get requestedUri;
 
   /**
    * The request headers.
+   *
+   * The request headers are immutable.

[Anders Johnsen, 2014/04/04 12:56:40]

This looks like half a copy of the above line. Consider:

  The returned [HttpHeaders] are immutable.

[Søren Gjesse, 2014/04/04 13:06:14]

Done.

    */
   HttpHeaders get headers;
 
   /**
    * The cookies in the request, from the Cookie headers.
    */
   List<Cookie> get cookies;
 
   /**
    * The persistent connection state signaled by the client.
@@ skipping 100 matching lines @@
    * the response is not known in advance set the content length to
    * -1 - which is also the default if not set.
    */
   int contentLength;
 
   /**
    * Gets and sets the status code. Any integer value is accepted. For
    * the official HTTP status codes use the fields from
    * [HttpStatus]. If no status code is explicitly set the default
    * value [HttpStatus.OK] is used.
+   *
+   * The status code must be set before the body is written
+   * to. Setting the status code after writing to the body will throw

[Anders Johnsen, 2014/04/04 12:56:40]

or closed.

[Søren Gjesse, 2014/04/04 13:06:14]

Done.

+   * a `StateError`.
    */
   int statusCode;
 
   /**
    * Gets and sets the reason phrase. If no reason phrase is explicitly
    * set a default reason phrase is provided.
+   *
+   * The reason phrase must be set before the body is written
+   * to. Setting the reason phrase after writing to the body will throw

[Anders Johnsen, 2014/04/04 12:56:40]

ditto.

[Søren Gjesse, 2014/04/04 13:06:14]

Done.

+   * a `StateError`.
    */
   String reasonPhrase;
 
   /**
    * Gets and sets the persistent connection state. The initial value
    * of this property is the persistent connection state from the
    * request.
    */
   bool persistentConnection;
 
   /**
    * Set and get the [deadline] for the response. The deadline is timed from the
    * time it's set. Setting a new deadline will override any previous deadline.
    * When a deadline is exceeded, the response will be closed and any further
    * data ignored.
    *
    * To disable a deadline, set the [deadline] to `null`.
    *
    * The [deadline] is `null` by default.
    */
   Duration deadline;
 
   /**
    * Returns the response headers.
+   *
+   * The response headers can be modified until the body is written
+   * to. After that they become immutable.

[Anders Johnsen, 2014/04/04 12:56:40]

ditto.

[Søren Gjesse, 2014/04/04 13:06:14]

Done.

    */
   HttpHeaders get headers;
 
   /**
    * Cookies to set in the client (in the 'set-cookie' header).
    */
   List<Cookie> get cookies;
 
   /**
    * Respond with a redirect to [location].
@@ skipping 457 matching lines @@
   Uri get uri;
 
   /**
    * Gets and sets the content length of the request. If the size of
    * the request is not known in advance set content length to -1,
    * which is also the default.
    */
   int contentLength;
 
   /**
-   * Returns the request headers.
+   * Returns the client request headers.
+   *
+   * The client request headers can be modified until the body is

[Anders Johnsen, 2014/04/04 12:56:40]

ditto, and below

[Søren Gjesse, 2014/04/04 13:06:14]

Done.

+   * written to. After that they become immutable.
    */
   HttpHeaders get headers;
 
   /**
    * Cookies to present to the server (in the 'cookie' header).
    */
   List<Cookie> get cookies;
 
   /**
    * A [HttpClientResponse] future that will complete once the response is
@@ skipping 26 matching lines @@
  *          .then((HttpClientRequeset request) => request.close())
  *          .then((HttpClientResponse response) {
  *            response.transform(UTF8.decoder).listen((contents) {
  *              // handle data
  *            });
  *          });
  */
 abstract class HttpClientResponse implements Stream<List<int>> {
   /**
    * Returns the status code.
+   *
+   * The status code must be set before the body is written
+   * to. Setting the status code after writing to the body will throw
+   * a `StateError`.
    */
   int get statusCode;
 
   /**
    * Returns the reason phrase associated with the status code.
+   *
+   * The reason phrase must be set before the body is written
+   * to. Setting the reason phrase after writing to the body will throw
+   * a `StateError`.
    */
   String get reasonPhrase;
 
   /**
    * Returns the content length of the response body. Returns -1 if the size of
    * the response body is not known in advance.
+   *
+   * If the content length needs to be set, it must be set before the
+   * body is written to. Setting the reason phrase after writing to
+   * the body will throw a `StateError`.
    */
   int get contentLength;
 
   /**
    * Gets the persistent connection state returned by the server.
+   *
+   * if the persistent connection state needs to be set, it must be
+   * set before the body is written to. Setting the reason phrase
+   * after writing to the body will throw a `StateError`.
    */
   bool get persistentConnection;
 
   /**
    * Returns whether the status code is one of the normal redirect
    * codes [HttpStatus.MOVED_PERMANENTLY], [HttpStatus.FOUND],
    * [HttpStatus.MOVED_TEMPORARILY], [HttpStatus.SEE_OTHER] and
    * [HttpStatus.TEMPORARY_REDIRECT].
    */
   bool get isRedirect;
@@ skipping 20 matching lines @@
    * even if the URL was already visited. The default value is [:false:].
    *
    * [redirect] will ignore [maxRedirects] and will always perform the redirect.
    */
   Future<HttpClientResponse> redirect([String method,
                                        Uri url,
                                        bool followLoops]);
 
 
   /**
-   * Returns the response headers.
+   * Returns the client response headers.
+   *
+   * The client response headers are immutable.
    */
   HttpHeaders get headers;
 
   /**
    * Detach the underlying socket from the HTTP client. When the
    * socket is detached the HTTP client will no longer perform any
    * operations on it.
    *
    * This is normally used when a HTTP upgrade is negotiated and the
    * communication should continue with a different protocol.
@@ skipping 109 matching lines @@
 class RedirectException implements HttpException {
   final String message;
   final List<RedirectInfo> redirects;
 
   const RedirectException(this.message, this.redirects);
 
   String toString() => "RedirectException: $message";
 
   Uri get uri => redirects.last.location;
 }