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

login
register
mail settings
Submitter Pierre-Yves David
Date Oct. 14, 2013, 4:33 p.m.
Message ID <740bf14129972cc0c440.1381768388@vulgaris>
Download mbox | patch
Permalink /patch/2769/
State Superseded, archived
Headers show

Comments

Pierre-Yves David - Oct. 14, 2013, 4:33 p.m.
# HG changeset patch
# User Pierre-Yves David <pierre-yves.david@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.
Augie Fackler - Oct. 16, 2013, 2:27 p.m.
On Mon, Oct 14, 2013 at 06:33:08PM +0200, pierre-yves.david@ens-lyon.org wrote:
> # HG changeset patch
> # User Pierre-Yves David <pierre-yves.david@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@selenic.com
> http://selenic.com/mailman/listinfo/mercurial-devel

Patch

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: