[PATCH 2 of 2] shelves: add minimal documentation to all functions

[Augie Fackler]

On Mon, Oct 14, 2013 at 06:33:08PM +0200, pierre-yves.david at ens-lyon.org wrote:
> # HG changeset patch
> # User Pierre-Yves David <pierre-yves.david at ens-lyon.org>
> # Date 1381768196 -7200
> #      Mon Oct 14 18:29:56 2013 +0200
> # Node ID 740bf14129972cc0c4406790785f392bec6aec52
> # Parent  af5270c0547ec771b2f3ad3f04ebf2f782e0aac9
> shelves: add minimal documentation to all functions
>
> There is a lot of functions in this extension. We had a small documentation help
> people getting started.

Queueing this, will do some English tweaks as a followup, thanks.

>
> diff --git a/hgext/shelve.py b/hgext/shelve.py
> --- a/hgext/shelve.py
> +++ b/hgext/shelve.py
> @@ -37,11 +37,13 @@ import errno
>  cmdtable = {}
>  command = cmdutil.command(cmdtable)
>  testedwith = 'internal'
>
>  class shelvedfile(object):
> -    """Handles common functions on shelve files (.hg/.files/.patch) using
> +    """Helper for the file storing a single shelve
> +
> +    Handles common functions on shelve files (.hg/.files/.patch) using
>      the vfs layer"""
>      def __init__(self, repo, name, filetype=None):
>          self.repo = repo
>          self.name = name
>          self.vfs = scmutil.vfs(repo.join('shelved'))
> @@ -78,11 +80,13 @@ class shelvedfile(object):
>              elif mode[0] == 'r':
>                  raise util.Abort(_("shelved change '%s' not found") %
>                                   self.name)
>
>  class shelvedstate(object):
> -    """Handles saving and restoring a shelved state. Ensures that different
> +    """Handle persistences during unshelving operation.
> +
> +    Handles saving and restoring a shelved state. Ensures that different
>      versions of a shelved state are possible and handles them appropriate"""
>      _version = 1
>      _filename = 'shelvedstate'
>
>      @classmethod
> @@ -112,10 +116,12 @@ class shelvedstate(object):
>      @classmethod
>      def clear(cls, repo):
>          util.unlinkpath(repo.join(cls._filename), ignoremissing=True)
>
>  def createcmd(ui, repo, pats, opts):
> +    """subcommand that create a new shelve"""
> +
>      def publicancestors(ctx):
>          """Compute the heads of the public ancestors of a commit.
>
>          Much faster than the revset heads(ancestors(ctx) - draft())"""
>          seen = set()
> @@ -241,10 +247,12 @@ def createcmd(ui, repo, pats, opts):
>          if tr:
>              tr.abort()
>          lockmod.release(lock, wlock)
>
>  def cleanupcmd(ui, repo):
> +    """subcommand that delete all shelves"""
> +
>      wlock = None
>      try:
>          wlock = repo.wlock()
>          for (name, _) in repo.vfs.readdir('shelved'):
>              suffix = name.rsplit('.', 1)[-1]
> @@ -252,10 +260,11 @@ def cleanupcmd(ui, repo):
>                  shelvedfile(repo, name).unlink()
>      finally:
>          lockmod.release(wlock)
>
>  def deletecmd(ui, repo, pats):
> +    """subcommand that delete a specific shelve"""
>      if not pats:
>          raise util.Abort(_('no shelved changes specified!'))
>      wlock = None
>      try:
>          wlock = repo.wlock()
> @@ -269,10 +278,11 @@ def deletecmd(ui, repo, pats):
>              raise util.Abort(_("shelved change '%s' not found") % name)
>      finally:
>          lockmod.release(wlock)
>
>  def listshelves(repo):
> +    """return all shelves in repo as list of  (time, filename)"""
>      try:
>          names = repo.vfs.readdir('shelved')
>      except OSError, err:
>          if err.errno != errno.ENOENT:
>              raise
> @@ -285,10 +295,11 @@ def listshelves(repo):
>          st = shelvedfile(repo, name).stat()
>          info.append((st.st_mtime, shelvedfile(repo, pfx).filename()))
>      return sorted(info, reverse=True)
>
>  def listcmd(ui, repo, pats, opts):
> +    """subcommand that display the list of shelve"""
>      pats = set(pats)
>      width = 80
>      if not ui.plain():
>          width = ui.termwidth()
>      namelabel = 'shelve.newest'
> @@ -332,19 +343,22 @@ def listcmd(ui, repo, pats, opts):
>                      ui.write(chunk, label=label)
>          finally:
>              fp.close()
>
>  def readshelvedfiles(repo, basename):
> +    """return the list of file touched in a shelve"""
>      fp = shelvedfile(repo, basename, 'files').opener()
>      return fp.read().split('\0')
>
>  def checkparents(repo, state):
> +    """check parent while resuming an unshelve"""
>      if state.parents != repo.dirstate.parents():
>          raise util.Abort(_('working directory parents do not match unshelve '
>                             'state'))
>
>  def unshelveabort(ui, repo, state, opts):
> +    """subcommand that abort an in-progress unshelve"""
>      wlock = repo.wlock()
>      lock = None
>      try:
>          checkparents(repo, state)
>          lock = repo.lock()
> @@ -371,10 +385,11 @@ def unshelveabort(ui, repo, state, opts)
>          ui.warn(_("unshelve of '%s' aborted\n") % state.name)
>      finally:
>          lockmod.release(lock, wlock)
>
>  def unshelvecleanup(ui, repo, name, opts):
> +    """remove related file after an unshelve"""
>      if not opts['keep']:
>          for filetype in 'hg files patch'.split():
>              shelvedfile(repo, name, filetype).unlink()
>
>  def finishmerge(ui, repo, ms, stripnodes, name, opts):
> @@ -382,10 +397,11 @@ def finishmerge(ui, repo, ms, stripnodes
>      dirstate = repo.dirstate
>      dirstate.setparents(dirstate._pl[0])
>      shelvedstate.clear(repo)
>
>  def unshelvecontinue(ui, repo, state, opts):
> +    """subcommand to continue an in-progress unshelve"""
>      # We're finishing off a merge. First parent is our original
>      # parent, second is the temporary "fake" commit we're unshelving.
>      wlock = repo.wlock()
>      lock = None
>      try:
> _______________________________________________
> Mercurial-devel mailing list
> Mercurial-devel at selenic.com
> http://selenic.com/mailman/listinfo/mercurial-devel