clarify lock_wait docstring

1.1 had some bug due to this, see PR #3981,
changeset 2f3e60d9d50d04dd5f09c7351acbcbba28646f36.

the bug does not apply to 1.0, but the improved doc strings might
still be useful.

borg/cache.py

@@ -51,6 +51,9 @@ class Cache:
 
     def __init__(self, repository, key, manifest, path=None, sync=True, do_files=False, warn_if_unencrypted=True,
                  lock_wait=None):
+        """
+        :param lock_wait: timeout for lock acquisition (int [s] or None [wait forever])
+        """
         self.lock = None
         self.timestamp = None
         self.lock = None

borg/locking.py

@@ -26,7 +26,7 @@ def get_id():
 
 class TimeoutTimer:
     """
-    A timer for timeout checks (can also deal with no timeout, give timeout=None [default]).
+    A timer for timeout checks (can also deal with "never timeout").
     It can also compute and optionally execute a reasonable sleep time (e.g. to avoid
     polling too often or to support thread/process rescheduling).
     """
@@ -34,10 +34,10 @@ class TimeoutTimer:
         """
         Initialize a timer.
 
-        :param timeout: time out interval [s] or None (no timeout)
+        :param timeout: time out interval [s] or None (never timeout, wait forever) [default]
         :param sleep: sleep interval [s] (>= 0: do sleep call, <0: don't call sleep)
                       or None (autocompute: use 10% of timeout [but not more than 60s],
-                      or 1s for no timeout)
+                      or 1s for "never timeout" mode)
         """
         if timeout is not None and timeout < 0:
             raise ValueError("timeout must be >= 0")