This is an archive of the discontinued Mercurial Phabricator instance.

Differential D1440

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

Authored by rlevasseur on Nov 16 2017, 6:28 PM.

Details

Reviewers
lothiraldan
durin42
Group Reviewers
hg-reviewers
Commits
rHGb22a0d9e0a83: docs: add args/returns docs for some cmdutil, context, and registrar functions
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.

Diff Detail

Repository
rHG Mercurial
Lint
Lint Skipped
Unit
Unit Tests Skipped

Event Timeline

rlevasseur created this revision.Nov 16 2017, 6:28 PM
lothiraldan requested changes to this revision.Nov 17 2017, 2:57 AM
lothiraldan added a subscriber: lothiraldan.

Looking good, just need a bunch of fixes. Also, did you tried generating the documentation, I'm not sure how 'parameters' would render in the documentation.

mercurial/context.py
637

I think there is a mistake here, immediate changesets of the current changeset.

638

s/decendents/descendants

mercurial/registrar.py
132

Should optionalrepo also be highlighted? `optionalrepo`

136

Should inferrepo also be highlighted? `inferrepo`

This revision now requires changes to proceed.Nov 17 2017, 2:57 AM
pulkit added a subscriber: pulkit.Nov 17 2017, 4:05 AM

I see you used the word string at few places, do you mean the Python string? If yes, that won't be true on Python 3 as most of the things are bytes.

rlevasseur marked 4 inline comments as done.Nov 18 2017, 4:10 PM
rlevasseur updated this revision to Diff 3628.
rlevasseur added a comment.Nov 18 2017, 4:14 PM
In D1440#23968, @pulkit wrote:

I see you used the word string at few places, do you mean the Python string? If yes, that won't be true on Python 3 as most of the things are bytes.

Ah good to know. I don't have much non-ascii stuff, so didn't notice. Ascii only unicode strings work OK -- if thats intentional/desired/supported, it should probably be doc'd as something like "bytes or ascii-encodable string" so callers don't think they have to use b'foo' or 'foo'.encode() everywhere. I've changed it to "bytes" for now -- let me know if you want "bytes or ascii-encodable string" (or equiv).

In D1440#23956, @lothiraldan wrote:

Also, did you tried generating the documentation, I'm not sure how 'parameters' would render in the documentation.

I ran make doc, but didn't see it output generated docs based on the code itself. Is there a command I missed? I was just assuming the format is RST for the doc strings, since that seems to be the popular format these days.

durin42 accepted this revision.Nov 20 2017, 6:28 PM
Closed by commit rHGb22a0d9e0a83: docs: add args/returns docs for some cmdutil, context, and registrar functions (authored by rlevasseur). · Explain WhyNov 20 2017, 6:36 PM
This revision was automatically updated to reflect the committed changes.

Revision Contents
Changeset List

PathPackages
Mmercurial/cmdutil.py (11 lines)
Mmercurial/context.py (13 lines)
Mmercurial/registrar.py (34 lines)

Diff 3583

mercurial/cmdutil.py

self.ui.pushbuffer() self.ui.pushbuffer()
diffordiffstat(self.ui, self.repo, diffopts, prev, node, diffordiffstat(self.ui, self.repo, diffopts, prev, node,
match=matchfn, stat=False) match=matchfn, stat=False)
self.ui.write((',\n "diff": "%s"') % j(self.ui.popbuffer())) self.ui.write((',\n "diff": "%s"') % j(self.ui.popbuffer()))
self.ui.write("\n }") self.ui.write("\n }")
class changeset_templater(changeset_printer): 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 # Arguments before "buffered" used to be positional. Consider not
# adding/removing arguments before "buffered" to not break callers. # adding/removing arguments before "buffered" to not break callers.
def __init__(self, ui, repo, tmplspec, matchfn=None, diffopts=None, def __init__(self, ui, repo, tmplspec, matchfn=None, diffopts=None,
buffered=False): buffered=False):
diffopts = diffopts or {} diffopts = diffopts or {}
changeset_printer.__init__(self, ui, repo, matchfn, diffopts, buffered) changeset_printer.__init__(self, ui, repo, matchfn, diffopts, buffered)
return logtemplatespec(None, mapfile) return logtemplatespec(None, mapfile)
if not tmpl: if not tmpl:
return logtemplatespec(None, None) return logtemplatespec(None, None)
return formatter.lookuptemplate(ui, 'changeset', tmpl) return formatter.lookuptemplate(ui, 'changeset', tmpl)
def makelogtemplater(ui, repo, tmpl, buffered=False): 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) spec = logtemplatespec(tmpl, None)
return changeset_templater(ui, repo, spec, buffered=buffered) return changeset_templater(ui, repo, spec, buffered=buffered)
def show_changeset(ui, repo, opts, buffered=False): def show_changeset(ui, repo, opts, buffered=False):
"""show one changeset using template or regular display. """show one changeset using template or regular display.
Display format will be the first non-empty hit of: Display format will be the first non-empty hit of:
1. option 'template' 1. option 'template'
copied = copies.pathcopies(repo[parent], ctx) copied = copies.pathcopies(repo[parent], ctx)
for f in actions['add'][0] + actions['undelete'][0] + actions['revert'][0]: for f in actions['add'][0] + actions['undelete'][0] + actions['revert'][0]:
if f in copied: if f in copied:
repo.dirstate.copy(copied[f], f) repo.dirstate.copy(copied[f], f)
class command(registrar.command): class command(registrar.command):
"""deprecated: used registrar.command instead"""
def _doregister(self, func, name, *args, **kwargs): def _doregister(self, func, name, *args, **kwargs):
func._deprecatedregistrar = True # flag for deprecwarn in extensions.py func._deprecatedregistrar = True # flag for deprecwarn in extensions.py
return super(command, self)._doregister(func, name, *args, **kwargs) return super(command, self)._doregister(func, name, *args, **kwargs)
# a list of (ui, repo, otherpeer, opts, missing) functions called by # a list of (ui, repo, otherpeer, opts, missing) functions called by
# commands.outgoing. "missing" is "missing" of the result of # commands.outgoing. "missing" is "missing" of the result of
# "findcommonoutgoing()" # "findcommonoutgoing()"
outgoinghooks = util.hooks() outgoinghooks = util.hooks()

mercurial/context.py

return self._changeset.files return self._changeset.files
def description(self): def description(self):
return self._changeset.description return self._changeset.description
def branch(self): def branch(self):
return encoding.tolocal(self._changeset.extra.get("branch")) return encoding.tolocal(self._changeset.extra.get("branch"))
def closesbranch(self): def closesbranch(self):
return 'close' in self._changeset.extra return 'close' in self._changeset.extra
def extra(self): def extra(self):
"""Return a dict of extra information."""
return self._changeset.extra return self._changeset.extra
def tags(self): def tags(self):
"""Return a list of string tag names"""
return self._repo.nodetags(self._node) return self._repo.nodetags(self._node)
def bookmarks(self): def bookmarks(self):
"""Return a list of string bookmark names."""
return self._repo.nodebookmarks(self._node) return self._repo.nodebookmarks(self._node)
def phase(self): def phase(self):
return self._repo._phasecache.phase(self._repo, self._rev) return self._repo._phasecache.phase(self._repo, self._rev)
def hidden(self): def hidden(self):
return self._rev in repoview.filterrevs(self._repo, 'visible') return self._rev in repoview.filterrevs(self._repo, 'visible')
def isinmemory(self): def isinmemory(self):
return False return False
def children(self): 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.
lothiraldanUnsubmitted
Done

I think there is a mistake here, immediate changesets of the current changeset.

lothiraldan: I think there is a mistake here, `immediate changesets of the current changeset`.
Use decendents() to recursively walk children.
lothiraldanUnsubmitted
Done

s/decendents/descendants

lothiraldan: s/decendents/descendants
"""
c = self._repo.changelog.children(self._node) c = self._repo.changelog.children(self._node)
return [changectx(self._repo, x) for x in c] return [changectx(self._repo, x) for x in c]
def ancestors(self): def ancestors(self):
for a in self._repo.changelog.ancestors([self._rev]): for a in self._repo.changelog.ancestors([self._rev]):
yield changectx(self._repo, a) yield changectx(self._repo, a)
def descendants(self): 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]): for d in self._repo.changelog.descendants([self._rev]):
yield changectx(self._repo, d) yield changectx(self._repo, d)
def filectx(self, path, fileid=None, filelog=None): def filectx(self, path, fileid=None, filelog=None):
"""get a file context from this changeset""" """get a file context from this changeset"""
if fileid is None: if fileid is None:
fileid = self.filenode(path) fileid = self.filenode(path)
return filectx(self._repo, path, fileid=fileid, return filectx(self._repo, path, fileid=fileid,

mercurial/registrar.py

"""Decorator to register a command function to table """Decorator to register a command function to table
This class receives a command table as its argument. The table should This class receives a command table as its argument. The table should
be a dict. be a dict.
The created object can be used as a decorator for adding commands to The created object can be used as a decorator for adding commands to
that command table. This accepts multiple arguments to define a command. 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. The `options` keyword argument is an iterable of tuples defining command
See ``mercurial.fancyopts.fancyopts()`` for the format of each tuple. 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. 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 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 The optionalrepo argument defines whether the command optionally requires
lothiraldanUnsubmitted
Done

Should optionalrepo also be highlighted? `optionalrepo`

lothiraldan: Should optionalrepo also be highlighted? ``optionalrepo``
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 The inferrepo argument defines whether to try to find a repository from the
lothiraldanUnsubmitted
Done

Should inferrepo also be highlighted? `inferrepo`

lothiraldan: Should inferrepo also be highlighted? ``inferrepo``
command line arguments. If True, arguments will be examined for potential command line arguments. If True, arguments will be examined for potential
repository locations. See ``findrepo()``. If a repository is found, it 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 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 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. be used to decide what level of access the command has on hidden commits.
The constants are: The constants are:
unrecoverablewrite is for those write commands which can't be recovered like unrecoverablewrite is for those write commands which can't be recovered like
push. push.
recoverablewrite is for write commands which can be recovered like commit. recoverablewrite is for write commands which can be recovered like commit.
readonly is for commands which are read only. 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" unrecoverablewrite = "unrecoverable"
recoverablewrite = "recoverable" recoverablewrite = "recoverable"
readonly = "readonly" readonly = "readonly"
possiblecmdtypes = {unrecoverablewrite, recoverablewrite, readonly} possiblecmdtypes = {unrecoverablewrite, recoverablewrite, readonly}