5 files changed, 81 insertions, 1 deletions
diff --git a/doc/source/command-objects/server.rst b/doc/source/command-objects/server.rst
index 6ae4d254..405c1830 100644
--- a/doc/source/command-objects/server.rst
+++ b/doc/source/command-objects/server.rst
@@ -187,6 +187,7 @@ List servers
         [--all-projects]
         [--project <project> [--project-domain <project-domain>]]
         [--long]
+        [--marker <server>]
 
 .. option:: --reservation-id <reservation-id>
 
@@ -250,6 +251,11 @@ List servers
 
     List additional fields in output
 
+.. option:: --marker <server>
+
+    The last server (name or ID) of the previous page. Display list of servers
+    after marker. Display all servers if not specified.
+
 server lock
 -----------
 
@@ -720,3 +726,18 @@ Unset server properties
 .. describe:: <server>
 
     Server (name or ID)
+
+server unshelve
+---------------
+
+Unshelve server(s)
+
+.. program:: server unshelve
+.. code:: bash
+
+    os server unshelve
+        <server> [<server> ...]
+
+.. describe:: <server>
+
+    Server(s) to unshelve (name or ID)
diff --git a/doc/source/command-objects/snapshot.rst b/doc/source/command-objects/snapshot.rst
index 7bfd1d92..e05673b8 100644
--- a/doc/source/command-objects/snapshot.rst
+++ b/doc/source/command-objects/snapshot.rst
@@ -60,6 +60,11 @@ List snapshots
 .. code:: bash
 
     os snapshot list
+        [--all-projects]
+
+.. option:: --all-projects
+
+    Include all projects (admin only)
 
 .. option:: --long
 
diff --git a/doc/source/command-wrappers.rst b/doc/source/command-wrappers.rst
new file mode 100644
index 00000000..b14eccdd
--- /dev/null
+++ b/doc/source/command-wrappers.rst
@@ -0,0 +1,52 @@
+======================
+Command Class Wrappers
+======================
+
+When we want to deprecate a command, policy says we need to alert the user.
+We do this with a message logged at WARNING level before any command output
+is emitted.
+
+OpenStackClient command classes are derived from the ``cliff`` classes.
+Cliff uses ``setuptools`` entry points for dispatching the parsed command
+to the respective handler classes.  This lends itself to modifying the
+command execution at run-time.
+
+The obvious approach to adding the deprecation message would be to just add
+the message to the command class ``take_action()`` method directly.  But then
+the various deprecations are scattered throughout the code base.  If we
+instead wrap the deprecated command class with a new class we can put all of
+the wrappers into a separate, dedicated module.  This also lets us leave the
+original class unmodified and puts all of the deprecation bits in one place.
+
+This is an example of a minimal wrapper around a command class that logs a
+deprecation message as a warning to the user then calls the original class.
+
+* Subclass the deprecated command.
+
+* Set class attribute ``deprecated`` to ``True`` to signal cliff to not
+  emit help text for this command.
+
+* Log the deprecation message at WARNING level and refer to the replacement
+  for the deprecated command in the log warning message.
+
+* Change the entry point class in ``setup.cfg`` to point to the new class.
+
+Example Deprecation Class
+-------------------------
+
+.. code-block: python
+
+    class ListFooOld(ListFoo):
+        """List resources"""
+
+        # This notifies cliff to not display the help for this command
+        deprecated = True
+
+        log = logging.getLogger('deprecated')
+
+        def take_action(self, parsed_args):
+            self.log.warning(
+                "%s is deprecated, use 'foobar list'",
+                getattr(self, 'cmd_name', 'this command'),
+            )
+            return super(ListFooOld, self).take_action(parsed_args)
diff --git a/doc/source/commands.rst b/doc/source/commands.rst
index 90aa481e..e0742ab4 100644
--- a/doc/source/commands.rst
+++ b/doc/source/commands.rst
@@ -183,7 +183,7 @@ Those actions with an opposite action are noted in parens if applicable.
 * ``revoke`` (``issue``) - revoke a token
 * ``save`` - download an object locally
 * ``set`` (``unset``) - set a property on the object, formerly called metadata
-* ``shelve`` (``unshelve``) - shelve one or more server
+* ``shelve`` (``unshelve``) - shelve one or more servers
 * ``show`` - display detailed information about the specific object
 * ``start`` (``stop``) - start one or more servers
 * ``stop`` (``start``) - stop one or more servers
@@ -192,6 +192,7 @@ Those actions with an opposite action are noted in parens if applicable.
 * ``unpause`` (``pause``) - return one or more paused servers to running state
 * ``unrescue`` (``rescue``) - return a server to normal boot mode
 * ``unset`` (``set``) - remove an attribute of the object
+* ``unshelve`` (``shelve``) - unshelve one or more servers
 
 
 Implementation
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 50b1fd24..66afc2b5 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -38,6 +38,7 @@ Developer Documentation
 
    developing
    command-options
+   command-wrappers
 
 Project Goals
 -------------