From c34cd865e549e32d404bf6159c4a8539dd8fdcad Mon Sep 17 00:00:00 2001
From: Tres Seaver <tseaver@palladion.com>
Date: Fri, 24 Feb 2017 13:01:47 -0500
Subject: [PATCH] Document '{Bucket,Blob}._STORAGE_CLASSES'.

Re-order to match canonical order in docs.

Add docstrings with links to relevant docs.

Explain why the two lists differ.
---
 storage/google/cloud/storage/blob.py   | 22 +++++++++++++++++++++-
 storage/google/cloud/storage/bucket.py | 16 ++++++++++++++--
 2 files changed, 35 insertions(+), 3 deletions(-)

diff --git a/storage/google/cloud/storage/blob.py b/storage/google/cloud/storage/blob.py
index d097c5eaafcc5..6af15e3e9a669 100644
--- a/storage/google/cloud/storage/blob.py
+++ b/storage/google/cloud/storage/blob.py
@@ -76,7 +76,27 @@ class Blob(_PropertyMixin):
     """Number (256 KB, in bytes) that must divide the chunk size."""
 
     _STORAGE_CLASSES = (
-        'STANDARD', 'NEARLINE', 'MULTI_REGIONAL', 'REGIONAL', 'COLDLINE')
+        'NEARLINE',
+        'MULTI_REGIONAL',
+        'REGIONAL',
+        'COLDLINE',
+        'STANDARD',  # alias for MULTI_REGIONAL/REGIONAL, based on location
+    )
+    """Allowed values for :attr:`storage_class`.
+
+    See:
+    https://cloud.google.com/storage/docs/json_api/v1/objects#storageClass
+    https://cloud.google.com/storage/docs/per-object-storage-class
+
+    .. note::
+       This list does not include 'DURABLE_REDUCED_AVAILABILITY', which
+       is only documented for buckets (and deprectated.
+
+    .. note::
+       The documentation does *not* mention 'STANDARD', but it is the value
+       assigned by the back-end for objects created in buckets with 'STANDARD'
+       set as their 'storage_class'.
+    """
 
     def __init__(self, name, bucket, chunk_size=None, encryption_key=None):
         super(Blob, self).__init__(name=name)
diff --git a/storage/google/cloud/storage/bucket.py b/storage/google/cloud/storage/bucket.py
index 04417094f258a..e856648182a6e 100644
--- a/storage/google/cloud/storage/bucket.py
+++ b/storage/google/cloud/storage/bucket.py
@@ -90,8 +90,20 @@ class Bucket(_PropertyMixin):
     This is used in Bucket.delete() and Bucket.make_public().
     """
 
-    _STORAGE_CLASSES = ('STANDARD', 'NEARLINE', 'DURABLE_REDUCED_AVAILABILITY',
-                        'MULTI_REGIONAL', 'REGIONAL', 'COLDLINE')
+    _STORAGE_CLASSES = (
+        'MULTI_REGIONAL',
+        'REGIONAL',
+        'NEARLINE',
+        'COLDLINE'
+        'STANDARD',  # alias for MULTI_REGIONAL/REGIONAL, based on location
+        'DURABLE_REDUCED_AVAILABILITY',  # deprecated
+    )
+    """Allowed values for :attr:`storage_class`.
+
+    See:
+    https://cloud.google.com/storage/docs/json_api/v1/buckets#storageClass
+    https://cloud.google.com/storage/docs/storage-classes
+    """
 
     def __init__(self, client, name=None):
         super(Bucket, self).__init__(name=name)