add a bit more docs to demonstrate handler usage in the decorator

Signed-off-by: Alfredo Deza <alfredo@deza.pe>

diff --git a/ceph_deploy/util/decorators.py b/ceph_deploy/util/decorators.py
index cc111e57aa63c8de8a21009664ae87cbbaa38a7e..9faa978aacff234034cd3cddca35e57ef576dd68 100644 (file)
--- a/ceph_deploy/util/decorators.py
+++ b/ceph_deploy/util/decorators.py
@@ -55,6 +55,22 @@ def catches(catch=None, handler=None, exit=True):
         def bar():
             some_call()
             print "Success!"
+
+    If adding a handler, it should accept a single argument, which would be the
+    exception that was raised, it would look like::
+
+        def my_handler(exc):
+            print 'Handling exception %s' % str(exc)
+            raise SystemExit
+
+        @catches(KeyboardInterrupt, handler=my_handler)
+        def bar():
+            some_call()
+
+    Note that the handler needs to raise its SystemExit if it wants to halt
+    execution, otherwise the decorator would continue as a normal try/except
+    block.
+
     """
     catch = catch or Exception
     logger = logging.getLogger('ceph_deploy')