[PATCH 7 of 7 evolve-ext] exthelper: update documentation with some examples for using registrar aliases

[Matt Harbison]

# HG changeset patch
# User Matt Harbison <matt_harbison at yahoo.com>
# Date 1546491714 18000
#      Thu Jan 03 00:01:54 2019 -0500
# Node ID a0b03d4cda7acec8e544e7c68041e876515c7dad
# Parent  0579af34a326c7a8d88aac713202bb6e90436bae
exthelper: update documentation with some examples for using registrar aliases

diff --git a/hgext3rd/evolve/exthelper.py b/hgext3rd/evolve/exthelper.py
--- a/hgext3rd/evolve/exthelper.py
+++ b/hgext3rd/evolve/exthelper.py
@@ -19,10 +19,57 @@
 class exthelper(object):
     """Helper for modular extension setup
 
-    A single helper should be instantiated for each extension. Helper
-    methods are then used as decorators for various purpose.
+    A single helper should be instantiated for each module of an
+    extension, where a command or function needs to be wrapped, or a
+    command, extension hook, fileset, revset or template needs to be
+    registered.  Helper methods are then used as decorators for
+    these various purposes.  If an extension spans multiple modules,
+    all helper instances should be merged in the main module.
 
     All decorators return the original function and may be chained.
+
+    Aside from the helper functions with examples below, several
+    registrar method aliases are available for adding commands,
+    configitems, filesets, revsets, and templates.  Simply decorate
+    the appropriate methods, and assign the corresponding exthelper
+    variable to a module level variable of the extension.  The
+    extension loading mechanism will handle the rest.
+
+    example::
+
+        # ext.py
+        eh = exthelper.exthelper()
+
+        # As needed:
+        cmdtable = eh.cmdtable
+        configtable = eh.configtable
+        filesetpredicate = eh.filesetpredicate
+        revsetpredicate = eh.revsetpredicate
+        templatekeyword = eh.templatekeyword
+
+        @eh.command('mynewcommand',
+            [('r', 'rev', [], _('operate on these revisions'))],
+            _('-r REV...'),
+            helpcategory=command.CATEGORY_XXX)
+        def newcommand(ui, repo, *revs, **opts):
+            # implementation goes here
+
+        eh.configitem('experimental', 'foo',
+            default=False,
+        )
+
+        @eh.filesetpredicate('lfs()')
+        def filesetbabar(mctx, x):
+            return mctx.predicate(...)
+
+        @eh.revsetpredicate('hidden')
+        def revsetbabar(repo, subset, x):
+            args = revset.getargs(x, 0, 0, 'babar accept no argument')
+            return [r for r in subset if 'babar' in repo[r].description()]
+
+        @eh.templatekeyword('babar')
+        def kwbabar(ctx):
+            return 'babar'
     """
 
     def __init__(self):
@@ -269,9 +316,18 @@
         This function takes two arguments, the container and the name of the
         function to wrap. The wrapping is performed during `uisetup`.
 
+        Adding attributes to a container like this is discouraged, because the
+        container modification is visible even in repositories that do not
+        have the extension loaded.  Therefore, care must be taken that the
+        function doesn't make assumptions that the extension was loaded for the
+        current repository.  For `ui` and `repo` instances, a better option is
+        to subclass the instance in `uipopulate` and `reposetup` respectively.
+
+        https://www.mercurial-scm.org/wiki/WritingExtensions
+
         example::
 
-            @eh.function(context.changectx, 'babar')
+            @eh.addattr(context.changectx, 'babar')
             def babar(ctx):
                 return 'babar' in ctx.description
         """