# HG changeset patch
# User Greg Ward <greg-hg@gerg.ca>
# Date 2009-08-05 12:42:57
# Node ID cfdcb7a465afadb0b1612330b19f80063039bd90
# Parent  6fdd39f52f7f4b974c90bcba4961da2656f01c57

localrepo: document the locking scheme a little better

- localrepo: document lock(), wlock() methods
- lock: add class docstring

diff --git a/mercurial/localrepo.py b/mercurial/localrepo.py
--- a/mercurial/localrepo.py
+++ b/mercurial/localrepo.py
@@ -651,6 +651,9 @@ class localrepository(repo.repository):
         return l
 
     def lock(self, wait=True):
+        '''Lock the repository store (.hg/store) and return a weak reference
+        to the lock. Use this before modifying the store (e.g. committing or
+        stripping). If you are opening a transaction, get a lock as well.)'''
         l = self._lockref and self._lockref()
         if l is not None and l.held:
             l.lock()
@@ -662,6 +665,9 @@ class localrepository(repo.repository):
         return l
 
     def wlock(self, wait=True):
+        '''Lock the non-store parts of the repository (everything under
+        .hg except .hg/store) and return a weak reference to the lock.
+        Use this before modifying files in .hg.'''
         l = self._wlockref and self._wlockref()
         if l is not None and l.held:
             l.lock()
diff --git a/mercurial/lock.py b/mercurial/lock.py
--- a/mercurial/lock.py
+++ b/mercurial/lock.py
@@ -1,4 +1,4 @@
-# lock.py - simple locking scheme for mercurial
+# lock.py - simple advisory locking scheme for mercurial
 #
 # Copyright 2005, 2006 Matt Mackall <mpm@selenic.com>
 #
@@ -10,6 +10,15 @@ import errno, os, socket, time
 import warnings
 
 class lock(object):
+    '''An advisory lock held by one process to control access to a set
+    of files.  Non-cooperating processes or incorrectly written scripts
+    can ignore Mercurial's locking scheme and stomp all over the
+    repository, so don't do that.
+
+    Typically used via localrepository.lock() to lock the repository
+    store (.hg/store/) or localrepository.wlock() to lock everything
+    else under .hg/.'''
+
     # lock is symlink on platforms that support it, file on others.
 
     # symlink is used because create of directory entry and contents