fill in provider docstrings

Added basic docstrings to box, dropbox, filesystem, github, googledrive,
s3 providers.  Includes: short header, url of online documentation,
quirks section

waterbutler/providers/box/provider.py

@@ -14,6 +14,11 @@
 
 
 class BoxProvider(provider.BaseProvider):
+    """Provider for the Box.com cloud storage service.
+
+    API docs: https://box-content.readme.io/reference
+    """
+
     NAME = 'box'
     BASE_URL = settings.BASE_URL
 

waterbutler/providers/dropbox/provider.py

@@ -13,6 +13,17 @@
 
 
 class DropboxProvider(provider.BaseProvider):
+    """Provider for the Dropbox.com cloud storage service.
+
+    This provider uses the v1 Dropbox API.  An ID-based v2 API is available, but the provider
+    has not yet been updated.
+
+    API docs: https://www.dropbox.com/developers-v1/core/docs
+
+    Quirks:
+
+    * Dropbox is a case-insensitive.
+    """
     NAME = 'dropbox'
     BASE_URL = settings.BASE_URL
 

waterbutler/providers/filesystem/provider.py

@@ -14,6 +14,11 @@
 
 
 class FileSystemProvider(provider.BaseProvider):
+    """Provider using the local filesystem as a backend-store
+
+    This provider is used for local testing.  Files are stored by hash, preserving
+    case-sensitivity on case-insensitive host filesystems.
+    """
     NAME = 'filesystem'
 
     def __init__(self, auth, credentials, settings):

waterbutler/providers/github/provider.py

@@ -48,6 +48,8 @@ class GitHubProvider(provider.BaseProvider):
         GH (dir):   'foo/bar'
         GH (file):  'foo/bar.txt'
 
+    API docs: https://developer.github.com/v3/
+
     Quirks:
 
     * git doesn't have a concept of empty folders, so this provider creates 0-byte ``.gitkeep``
@@ -56,6 +58,11 @@ class GitHubProvider(provider.BaseProvider):
     * The ``contents`` endpoint cannot be used to fetch metadata reliably for all files. Requesting
       a file that is larger than 1Mb will result in a error response directing you to the ``blob``
       endpoint.  A recursive tree fetch may be used instead.
+
+    * The tree endpoint truncates results after a large number of files.  It does not provide a way
+      to page through the tree.  Since move, copy, and folder delete operations rely on whole-tree
+      replacement, they cannot be reliably supported for large repos.  Attempting to use them will
+      throw a 501 Not Implemented error.
     """
     NAME = 'github'
     BASE_URL = settings.BASE_URL

waterbutler/providers/googledrive/provider.py

@@ -35,6 +35,25 @@ class GoogleDrivePath(path.WaterButlerPath):
 
 
 class GoogleDriveProvider(provider.BaseProvider):
+    """Provider for Google's Drive cloud storage service.
+
+    This provider uses the v2 Drive API.  A v3 API is available, but this provider has not yet
+    been updated.
+
+    API docs: https://developers.google.com/drive/v2/reference/
+
+    Quirks:
+
+    * Google doc files (``.gdoc``, ``.gsheet``, ``.gsheet``, ``.gdraw``) cannot be downloaded in
+      their native format and must be exported to another format.  e.g. ``.gdoc`` to ``.docx``
+
+    * Some Google doc files (currently ``.gform`` and ``.gmap``) do not have an available export
+      format and cannot be downloaded at all.
+
+    * Google Drive is not really a filesystem.  Folders are actually labels, meaning a file ``foo``
+      could be in two folders (ex. ``A``, ``B``) at the same time.  Deleting ``/A/foo`` will
+      cause ``/B/foo`` to be deleted as well.
+    """
     NAME = 'googledrive'
     BASE_URL = settings.BASE_URL
     FOLDER_MIME_TYPE = 'application/vnd.google-apps.folder'

waterbutler/providers/s3/provider.py

@@ -28,16 +28,19 @@
 
 
 class S3Provider(provider.BaseProvider):
-    """Provider for the Amazon's S3
+    """Provider for Amazon's S3 cloud storage service.
+
+    API docs: http://docs.aws.amazon.com/AmazonS3/latest/API/Welcome.html
 
     Quirks:
-        On S3, folders are not first-class objects, but are instead inferred
-        from the names of their children.  A regular DELETE request issued
-        against a folder will not work unless that folder is completely empty.
-        To fully delete an occupied folder, we must delete all of the comprising
-        objects.  Amazon provides a bulk delete operation to simplify this.
 
-        A GET prefix query against a non-existant path returns 200
+    * On S3, folders are not first-class objects, but are instead inferred
+      from the names of their children.  A regular DELETE request issued
+      against a folder will not work unless that folder is completely empty.
+      To fully delete an occupied folder, we must delete all of the comprising
+      objects.  Amazon provides a bulk delete operation to simplify this.
+
+    * A GET prefix query against a non-existent path returns 200
     """
     NAME = 's3'