diff -r 6fdd39f52f7f -r cfdcb7a465af mercurial/lock.py
--- a/mercurial/lock.py	Wed Aug 05 17:20:47 2009 +0200
+++ b/mercurial/lock.py	Wed Aug 05 14:42:57 2009 +0200
@@ -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 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