Fix media metadata-only uploads and various documentation fixes. - #230

Still have to update README and Migrating.

Possible fix for #229

JSDoc requires changes as well. It has to go in a major release (1.1.0).

Fixed JSDoc.

Major? http://semver.org/ Major would be 2.0.0. And we are creating changes that break existing functionality. I suppose the change is small enough that it can be neglected as a major.

We can do it without breaking backwards compatibility - simply check if the input to the media param has mimeType property and depending on that use either the old or the new logic.

Optionally, we can console.error when the old behaviour is used so that the programmer is informed about this API being changed.

Not reliably enough because a stream object can be provided and for all we know, it could have the mimeType property defined. I would rather not assume and instead just release it under 1.1. Nobody should use the old functionality because it is inherently broken for many APIs anyway. Plus migrating to new changes is rather easy.

Effectively, the issue with 1.0.x is it didn't take into consideration the case of metadata-only media requests. In this fix, we check whether the user has provided a media.body, and if they have, we make the multipart request as normal. If they don't provide a media.body we make a simple json request where the body is just the resource. The Content-Type of the request can only be specified when a media.body is specified, in which case you can set the mime-type using media.mimeType. Fallback mime-type provided by resource.mimeType option, "text/plain" for strings or "application/octet-stream" as last chance.

LGTM.

We need a minor release, anyone who uses ~1.0.0 will be able to get the update, whereas if you're strictly depending on 1.0.x, you won't.