[doc] converting old doc style to YARD doc style
[doc] is there a better way to format nested responses?
Make use of #persisted? method

In many places we were checking for identity which was the shorthand for
checking if the resource had been saved by the service.

The #persisted? method was added to show a clearer intent and also offer
minimal ActiveModel interface
add GitHub Flavored Markdown to README

* This makes the example code easier to read,
  especially when perusing the docs on github
[Brightbox] Adds #dns_name to server

Little known fact is that the public version of the domain name of a
Brightbox cloud server is the `fqdn` prefixed with public.

This is now fixed here until it is fixed in the main API and the value
can be referenced directly from the response.
Merge pull request #1417 from brightbox/add_dns_name

[Brightbox] Adds #dns_name to server
Merge pull request #1413 from phlipper/patch-1

add GitHub Flavored Markdown to README
Merge pull request #1412 from westonplatter/aws_docs

[docs] question about how to format AWS nested responses
use CGI.escapeHTML instead of CGI.escape

CGI.escape creates URL-safe encodings, but we need XML-safe encodings.
If the key name has a "/" in it (as for a directory structure) it gets
replaced with a URL-safe "%2F" which S3 treats as a literal part of the
key name. We only need to escape the parts of the key that could result
in malformed XML.
Merge pull request #1421 from jparker/delete_multiple_objects_escape_xml

use CGI.escapeHTML instead of CGI.escape
[docs::was::storage] i was wrong. this is an int describing "number of seconds before expiration"
to confirm, go to -- http://docs.aws.amazon.com/AmazonS3/latest/API/RESTObjectPUT.html
search for -- expires
[docs::was::storage] formatting
[docs::was::storage] added more description
[docs::was::storage] added docs for other public methods
[docs::was::storage] added URL for list of S3 docs about Restful HTTP API
[docs::was::storage] this consistently spaces all methods 2 lines from each other
[vsphere] allow to create a vm with multiple disks.

unitNumber has to be unique.
add IamInstanceProfile abilitie
Merge pull request #1423 from westonplatter/aws_docs

more docs for Fog::AWS::Storage::Model::File
Merge pull request #1416 from fog/use_persisted

Make use of #persisted? method