documentation for headers - add sample how to use it

[surfmuggle]

Add example to docs how to set Client.headers

As in https://github.com/dart-lang/http/issues/193 i had the same problem that i did not understand how to use the headers property of the Request class.

The docs for headers are

final Map<String, String> headers;

So i tried these two approaches

var request = new Request(....)
// wrong 1
request.headers = {'Authorization':'foo:bar'}; 
// wrong 2
request.headers({'Authorization':'foo:bar'});

After asking on stackoverflow i now know that it has to be used like this

  final client = http.Client();
  final request = http.Request('GET', urlHttpBin);
  request.headers['Authorization'] = 'Basic $creds64';

It would be great for newcommers if the docs for headers would have an example like above (or similar).

[brian030128]

request.headers = {'Authorization':'foo:bar'};

It's a final parameter, so you can't reassign it.

request.headers({'Authorization':'foo:bar'});

There's no such format in dart.

Users should at least know how to write dart, so I don't think this would be necassary.

[surfmuggle]

I understand that the docs about a Map has a sample

You can create the same objects using a Map constructor:

var gifts = Map<String, String>();
gifts['first'] = 'partridge';

And Dart Variables has this sample

Here’s an example of creating and setting a final variable:

final name = 'Bob'; // Without a type annotation
final String nickname = 'Bobby';

In make a network request this is written

Some server requests require more information, such as authentication or user-agent information; in this case you might need to include HTTP headers. You can specify headers by passing in a Map<String, String> of the key-value pairs as the headers optional named parameter:

await http.get(Uri.https('dart.dev', '/f/packages/http.json'),
    headers: {'User-Agent': '<product name>/<product-version>'});

But nonetheless i believe that the docs for headers could use a sample as well.