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

[rlevasseur (Richard Levasseur)]

rlevasseur created this revision.
Herald added a subscriber: mercurial-devel.
Herald added a reviewer: hg-reviewers.

REVISION SUMMARY
  When writing my first extension, I found it hard to figure out these functions.
  I figured documenting their inputs/outputs would help future authors who
  are new to the codebase.

REPOSITORY
  rHG Mercurial

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,25 +112,31 @@
     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 string.
 
-    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.
+    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.
+    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
@@ -141,6 +147,18 @@
     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 string tag names"""
         return self._repo.nodetags(self._node)
     def bookmarks(self):
+        """Return a list of string 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.
+
+        Children are the immediate changesets of the current changeset.
+        Use decendents() 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,7 @@
     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' string."""
     spec = logtemplatespec(tmpl, None)
     return changeset_templater(ui, repo, spec, buffered=buffered)
 
@@ -3860,6 +3866,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
Cc: mercurial-devel