D1440: docs: add args/returns docs for some cmdutil, context, and registrar functions

[rlevasseur (Richard Levasseur)]

rlevasseur updated this revision to Diff 3628.
rlevasseur marked 4 inline comments as done.

REPOSITORY
  rHG Mercurial

CHANGES SINCE LAST UPDATE
  https://phab.mercurial-scm.org/D1440?vs=3583&id=3628

REVISION DETAIL
  https://phab.mercurial-scm.org/D1440

AFFECTED FILES
  mercurial/cmdutil.py
  mercurial/context.py
  mercurial/registrar.py

CHANGE DETAILS

diff --git a/mercurial/registrar.py b/mercurial/registrar.py
--- a/mercurial/registrar.py
+++ b/mercurial/registrar.py
@@ -112,35 +112,53 @@
     The created object can be used as a decorator for adding commands to
     that command table. This accepts multiple arguments to define a command.
 
-    The first argument is the command name.
+    The first argument is the command name (as bytes).
 
-    The options argument is an iterable of tuples defining command arguments.
-    See ``mercurial.fancyopts.fancyopts()`` for the format of each tuple.
+    The `options` keyword argument is an iterable of tuples defining command
+    arguments. See ``mercurial.fancyopts.fancyopts()`` for the format of each
+    tuple.
 
-    The synopsis argument defines a short, one line summary of how to use the
+    The `synopsis` argument defines a short, one line summary of how to use the
     command. This shows up in the help output.
 
-    The norepo argument defines whether the command does not require a
+    There are three arguments that control what repository (if any) is found
+    and passed to the decorated function: `norepo`, `optionalrepo`, and
+    `inferrepo`.
+
+    The `norepo` argument defines whether the command does not require a
     local repository. Most commands operate against a repository, thus the
-    default is False.
+    default is False. When True, no repository will be passed.
 
-    The optionalrepo argument defines whether the command optionally requires
-    a local repository.
+    The `optionalrepo` argument defines whether the command optionally requires
+    a local repository. If no repository can be found, None will be passed
+    to the decorated function.
 
-    The inferrepo argument defines whether to try to find a repository from the
-    command line arguments. If True, arguments will be examined for potential
-    repository locations. See ``findrepo()``. If a repository is found, it
-    will be used.
+    The `inferrepo` argument defines whether to try to find a repository from
+    the command line arguments. If True, arguments will be examined for
+    potential repository locations. See ``findrepo()``. If a repository is
+    found, it will be used and passed to the decorated function.
 
     There are three constants in the class which tells what type of the command
     that is. That information will be helpful at various places. It will be also
     be used to decide what level of access the command has on hidden commits.
     The constants are:
 
-    unrecoverablewrite is for those write commands which can't be recovered like
-    push.
-    recoverablewrite is for write commands which can be recovered like commit.
-    readonly is for commands which are read only.
+    `unrecoverablewrite` is for those write commands which can't be recovered
+    like push.
+    `recoverablewrite` is for write commands which can be recovered like commit.
+    `readonly` is for commands which are read only.
+
+    The signature of the decorated function looks like this:
+        def cmd(ui[, repo] [, <args>] [, <options>])
+
+      `repo` is required if `norepo` is False.
+      `<args>` are positional args (or `*args`) arguments, of non-option
+      arguments from the command line.
+      `<options>` are keyword arguments (or `**options`) of option arguments
+      from the command line.
+
+    See the WritingExtensions and MercurialApi documentation for more exhaustive
+    descriptions and examples.
     """
 
     unrecoverablewrite = "unrecoverable"
diff --git a/mercurial/context.py b/mercurial/context.py
--- a/mercurial/context.py
+++ b/mercurial/context.py
@@ -615,10 +615,13 @@
     def closesbranch(self):
         return 'close' in self._changeset.extra
     def extra(self):
+        """Return a dict of extra information."""
         return self._changeset.extra
     def tags(self):
+        """Return a list of byte tag names"""
         return self._repo.nodetags(self._node)
     def bookmarks(self):
+        """Return a list of byte bookmark names."""
         return self._repo.nodebookmarks(self._node)
     def phase(self):
         return self._repo._phasecache.phase(self._repo, self._rev)
@@ -629,15 +632,23 @@
         return False
 
     def children(self):
-        """return contexts for each child changeset"""
+        """return list of changectx contexts for each child changeset.
+
+        This returns only the immediate child changesets. Use descendants() to
+        recursively walk children.
+        """
         c = self._repo.changelog.children(self._node)
         return [changectx(self._repo, x) for x in c]
 
     def ancestors(self):
         for a in self._repo.changelog.ancestors([self._rev]):
             yield changectx(self._repo, a)
 
     def descendants(self):
+        """Recursively yield all children of the changeset.
+
+        For just the immediate children, use children()
+        """
         for d in self._repo.changelog.descendants([self._rev]):
             yield changectx(self._repo, d)
 
diff --git a/mercurial/cmdutil.py b/mercurial/cmdutil.py
--- a/mercurial/cmdutil.py
+++ b/mercurial/cmdutil.py
@@ -1850,7 +1850,13 @@
         self.ui.write("\n }")
 
 class changeset_templater(changeset_printer):
-    '''format changeset information.'''
+    '''format changeset information.
+
+    Note: there are a variety of convenience functions to build a
+    changeset_templater for common cases. See functions such as:
+    makelogtemplater, show_changeset, buildcommittemplate, or other
+    functions that use changesest_templater.
+    '''
 
     # Arguments before "buffered" used to be positional. Consider not
     # adding/removing arguments before "buffered" to not break callers.
@@ -1972,7 +1978,8 @@
     return formatter.lookuptemplate(ui, 'changeset', tmpl)
 
 def makelogtemplater(ui, repo, tmpl, buffered=False):
-    """Create a changeset_templater from a literal template 'tmpl'"""
+    """Create a changeset_templater from a literal template 'tmpl'
+    byte-string."""
     spec = logtemplatespec(tmpl, None)
     return changeset_templater(ui, repo, spec, buffered=buffered)
 
@@ -3860,6 +3867,7 @@
             repo.dirstate.copy(copied[f], f)
 
 class command(registrar.command):
+    """deprecated: used registrar.command instead"""
     def _doregister(self, func, name, *args, **kwargs):
         func._deprecatedregistrar = True  # flag for deprecwarn in extensions.py
         return super(command, self)._doregister(func, name, *args, **kwargs)



To: rlevasseur, #hg-reviewers, lothiraldan
Cc: pulkit, lothiraldan, mercurial-devel