largefiles: add some docstrings

hgext/largefiles/lfutil.py

@@ -39,6 +39,7 b' def getminsize(ui, assumelfiles, opt, de'
     return lfsize
 
 def link(src, dest):
+    """Try to create hardlink - if that fails, efficiently make a copy."""
     util.makedirs(os.path.dirname(dest))
     try:
         util.oslink(src, dest)
@@ -86,6 +87,9 b' def inusercache(ui, hash):'
     return os.path.exists(path)
 
 def findfile(repo, hash):
+    '''Return store path of the largefile with the specified hash.
+    As a side effect, the file might be linked from user cache.
+    Return None if the file can't be found locally.'''
     path, exists = findstorepath(repo, hash)
     if exists:
         repo.ui.note(_('found %s in store\n') % hash)
@@ -176,9 +180,13 b' def listlfiles(repo, rev=None, matcher=N'
             if rev is not None or repo.dirstate[f] != '?']
 
 def instore(repo, hash, forcelocal=False):
+    '''Return true if a largefile with the given hash exists in the user
+    cache.'''
     return os.path.exists(storepath(repo, hash, forcelocal))
 
 def storepath(repo, hash, forcelocal=False):
+    '''Return the correct location in the repository largefiles cache for a
+    file with the given hash.'''
     if not forcelocal and repo.shared():
         return repo.vfs.reljoin(repo.sharedpath, longname, hash)
     return repo.join(longname, hash)
@@ -257,6 +265,8 b' def copytostoreabsolute(repo, file, hash'
         linktousercache(repo, hash)
 
 def linktousercache(repo, hash):
+    '''Link / copy the largefile with the specified hash from the store
+    to the cache.'''
     path = usercachepath(repo.ui, hash)
     link(storepath(repo, hash), path)
 
@@ -394,6 +404,7 b' def unixpath(path):'
     return util.pconvert(os.path.normpath(path))
 
 def islfilesrepo(repo):
+    '''Return true if the repo is a largefile repo.'''
     if ('largefiles' in repo.requirements and
             any(shortnameslash in f[0] for f in repo.store.datafiles())):
         return True

hgext/largefiles/proto.py

@@ -22,8 +22,8 b' ssholdcallstream = None'
 httpoldcallstream = None
 
 def putlfile(repo, proto, sha):
-    '''Put a largefile into a repository's local store and into the
-    user cache.'''
+    '''Server command for putting a largefile into a repository's local store
+    and into the user cache.'''
     proto.redirect()
 
     path = lfutil.storepath(repo, sha)
@@ -47,8 +47,8 b' def putlfile(repo, proto, sha):'
     return wireproto.pushres(0)
 
 def getlfile(repo, proto, sha):
-    '''Retrieve a largefile from the repository-local cache or system
-    cache.'''
+    '''Server command for retrieving a largefile from the repository-local
+    cache or user cache.'''
     filename = lfutil.findfile(repo, sha)
     if not filename:
         raise error.Abort(_('requested largefile %s not present in cache')
@@ -68,8 +68,8 b' def getlfile(repo, proto, sha):'
     return wireproto.streamres(generator())
 
 def statlfile(repo, proto, sha):
-    '''Return '2\n' if the largefile is missing, '0\n' if it seems to be in
-    good condition.
+    '''Server command for checking if a largefile is present - returns '2\n' if
+    the largefile is missing, '0\n' if it seems to be in good condition.
 
     The value 1 is reserved for mismatched checksum, but that is too expensive
     to be verified on every stat and must be caught be running 'hg verify'
@@ -151,9 +151,12 b' def wirereposetup(ui, repo):'
 
 # advertise the largefiles=serve capability
 def capabilities(repo, proto):
+    '''Wrap server command to announce largefile server capability'''
     return capabilitiesorig(repo, proto) + ' largefiles=serve'
 
 def heads(repo, proto):
+    '''Wrap server command - largefile capable clients will know to call
+    lheads instead'''
     if lfutil.islfilesrepo(repo):
         return wireproto.ooberror(LARGEFILES_REQUIRED_MSG)
     return wireproto.heads(repo, proto)