Merge pull request #241 from dhermes/docstrings-storage

Documenting undocumented classes/methods/etc. in gcloud.storage.
Adding pylintrc config and custom runner and making it pass.

Some key things to notice:
- The tools (pep8 / pylint) disagree about continutation lines.
  This is because PEP8 is ambiguous about "multi-line constructs".
  One of the examples for bracket indentation in the PEP is

      my_list = [
          1, 2, 3,
          4, 5, 6,
          ]

  but the PEP doesn't explicity say whether or not

      my_list = [1, 2, 3,
                 4, 5, 6,
                 ]

  would be allowed. As it turns out, pep8 (the tool) considers
  the latter to be a continuation while pylint does not.
- I changed all indentation where this was a problem, but was
  intentionally inconsistent. This way we can see "all options"
  and discuss whichever is preferred.
- I made a _MetadataMixin helper class for methods shared between
  storage.Bucket and storage.Key. I did not refactor the affected
  tests but they do still give 100% coverage.
- To silence docstrings warnings I added many bogus docstrings
  without actually documenting the given objects.
- I factored out part of
      storage.connection.Connection.generate_signed_url
  into a _get_expiration_seconds() method and added tests.
  This method is untested (has pragma no cover) and is still very long.
  I refactored because pylint complained about too many locals.
- I made sure tox -e lint and tox -e cover passed.
- I increased the maximum number of arguments from 5 to 10 and
  the maximum public methods from 20 to 30. Offenders were:
    - storage.connection.Connection.make_request (6 arguments)
    - storage.connection.Connection.api_request (9 arguments)
    - storage.connection.Connection.generate_signed_url (6 arguments)
    - storage.bucket.Bucket (27 public methods) and
    - storage.key.Key (23 public methods)
  I think refactoring these should be considered (though is not
  mandatory). I certainly don't know a good solution for the class
  public methods.
Removing pylint statements in datastore.entity.

Rolls back changes put in #189 that are no longer
necessary.
Using calendar.timegm instead of time.mktime.

Note that time.mktime says:
"Convert a time tuple in local time to seconds since the Epoch."
while calendar.timegm says:
"handy function to calculate Unix timestamp from GMT."

This is why tests were failing with local timezones seeming
to matter (because they did with time.mktime).

Also changed import of datetime in datastore._helpers
to make namespace/class confusion clear. I noticed this when
looking for other uses of calendar.timegm in the codebase.
Removing comment hash from docstring.
Adding docstrings to new code in pylint fix.
Using custom utcnow method in storage.connection to avoid test hacks.

H/T: @tseaver for feedback