Spiff up docs for *_with_prefix

Following up on comments in [1], clarify and unify the docs for the
following lockutils methods:

- lock_with_prefix
- synchronized_with_prefix
- remove_external_lock_file_with_prefix

[1] I4e723ee3be1e57c543684390b607c84388c6e930

Change-Id: I4179e8732dba7367bd0c835cbd11939ca7b8cc42

1 files changed, 34 insertions, 11 deletions

diff --git a/oslo_concurrency/lockutils.py b/oslo_concurrency/lockutils.py
index ba0d0a5..7fe049b 100644
--- a/oslo_concurrency/lockutils.py
+++ b/oslo_concurrency/lockutils.py
@@ -289,7 +289,9 @@ def lock_with_prefix(lock_file_prefix):
         (in nova/utils.py)
         from oslo_concurrency import lockutils
 
-        lock = lockutils.lock_with_prefix('nova-')
+        _prefix = 'nova'
+        lock = lockutils.lock_with_prefix(_prefix)
+        lock_cleanup = lockutils.remove_external_lock_file_with_prefix(_prefix)
 
 
         (in nova/foo.py)
@@ -298,8 +300,14 @@ def lock_with_prefix(lock_file_prefix):
         with utils.lock('mylock'):
            ...
 
-    The lock_file_prefix argument is used to provide lock files on disk with a
-    meaningful prefix.
+    Eventually clean up with::
+
+        lock_cleanup('mylock')
+
+    :param lock_file_prefix: A string used to provide lock files on disk with a
+        meaningful prefix. Will be separated from the lock name with a hyphen,
+        which may optionally be included in the lock_file_prefix (e.g.
+        ``'nova'`` and ``'nova-'`` are equivalent).
     """
     return functools.partial(lock, lock_file_prefix=lock_file_prefix)
 
@@ -373,7 +381,9 @@ def synchronized_with_prefix(lock_file_prefix):
         (in nova/utils.py)
         from oslo_concurrency import lockutils
 
-        synchronized = lockutils.synchronized_with_prefix('nova-')
+        _prefix = 'nova'
+        synchronized = lockutils.synchronized_with_prefix(_prefix)
+        lock_cleanup = lockutils.remove_external_lock_file_with_prefix(_prefix)
 
 
         (in nova/foo.py)
@@ -383,8 +393,14 @@ def synchronized_with_prefix(lock_file_prefix):
         def bar(self, *args):
            ...
 
-    The lock_file_prefix argument is used to provide lock files on disk with a
-    meaningful prefix.
+    Eventually clean up with::
+
+        lock_cleanup('mylock')
+
+    :param lock_file_prefix: A string used to provide lock files on disk with a
+        meaningful prefix. Will be separated from the lock name with a hyphen,
+        which may optionally be included in the lock_file_prefix (e.g.
+        ``'nova'`` and ``'nova-'`` are equivalent).
     """
 
     return functools.partial(synchronized, lock_file_prefix=lock_file_prefix)
@@ -398,18 +414,25 @@ def remove_external_lock_file_with_prefix(lock_file_prefix):
         (in nova/utils.py)
         from oslo_concurrency import lockutils
 
-        synchronized = lockutils.synchronized_with_prefix('nova-')
-        synchronized_remove = lockutils.remove_external_lock_file_with_prefix(
-            'nova-')
+        _prefix = 'nova'
+        synchronized = lockutils.synchronized_with_prefix(_prefix)
+        lock = lockutils.lock_with_prefix(_prefix)
+        lock_cleanup = lockutils.remove_external_lock_file_with_prefix(_prefix)
 
         (in nova/foo.py)
         from nova import utils
 
         @utils.synchronized('mylock')
         def bar(self, *args):
-           ...
+            ...
+
+        def baz(self, *args):
+            ...
+            with utils.lock('mylock'):
+                ...
+            ...
 
-        <eventually call synchronized_remove('mylock') to cleanup>
+        <eventually call lock_cleanup('mylock') to clean up>
 
     The lock_file_prefix argument is used to provide lock files on disk with a
     meaningful prefix.