changeset 46871:887f89b100ac

exthelper: improve docs to indicate what module vars are needed

I recently tried creating an extension "from scratch" using exthelper, and it
wasn't obvious that you needed these. I believe that a careful reading of one of
the comments would tell you that they were required, but it's easy to miss and
having the examples be "complete" is helpful.

Differential Revision: https://phab.mercurial-scm.org/D10295

--- a/mercurial/exthelper.py	Mon Apr 05 12:44:33 2021 -0400
+++ b/mercurial/exthelper.py	Tue Mar 30 13:05:22 2021 -0700
@@ -46,13 +46,22 @@
         # ext.py
         eh = exthelper.exthelper()
 
-        # As needed:
+        # As needed (failure to do this will mean your registration will not
+        # happen):
         cmdtable = eh.cmdtable
         configtable = eh.configtable
         filesetpredicate = eh.filesetpredicate
         revsetpredicate = eh.revsetpredicate
         templatekeyword = eh.templatekeyword
 
+        # As needed (failure to do this will mean your eh.wrap*-decorated
+        # functions will not wrap, and/or your eh.*setup-decorated functions
+        # will not execute):
+        uisetup = eh.finaluisetup
+        extsetup = eh.finalextsetup
+        reposetup = eh.finalreposetup
+        uipopulate = eh.finaluipopulate
+
         @eh.command(b'mynewcommand',
             [(b'r', b'rev', [], _(b'operate on these revisions'))],
             _(b'-r REV...'),
@@ -155,7 +164,7 @@
             c(ui)
 
     def finalextsetup(self, ui):
-        """Method to be used as a the extension extsetup
+        """Method to be used as the extension extsetup
 
         The following operations belong here:
 
@@ -201,6 +210,9 @@
 
         example::
 
+            # Required, otherwise your uisetup function(s) will not execute.
+            uisetup = eh.finaluisetup
+
             @eh.uisetup
             def setupbabar(ui):
                 print('this is uisetup!')
@@ -213,6 +225,9 @@
 
         example::
 
+            # Required, otherwise your uipopulate function(s) will not execute.
+            uipopulate = eh.finaluipopulate
+
             @eh.uipopulate
             def setupfoo(ui):
                 print('this is uipopulate!')
@@ -225,6 +240,9 @@
 
         example::
 
+            # Required, otherwise your extsetup function(s) will not execute.
+            extsetup = eh.finalextsetup
+
             @eh.extsetup
             def setupcelestine(ui):
                 print('this is extsetup!')
@@ -237,6 +255,9 @@
 
         example::
 
+            # Required, otherwise your reposetup function(s) will not execute.
+            reposetup = eh.finalreposetup
+
             @eh.reposetup
             def setupzephir(ui, repo):
                 print('this is reposetup!')
@@ -258,6 +279,11 @@
 
         example::
 
+            # Required if `extension` is not provided
+            uisetup = eh.finaluisetup
+            # Required if `extension` is provided
+            extsetup = eh.finalextsetup
+
             @eh.wrapcommand(b'summary')
             def wrapsummary(orig, ui, repo, *args, **kwargs):
                 ui.note(b'Barry!')
@@ -298,8 +324,11 @@
 
         example::
 
-            @eh.function(discovery, b'checkheads')
-            def wrapfunction(orig, *args, **kwargs):
+            # Required, otherwise the function will not be wrapped
+            uisetup = eh.finaluisetup
+
+            @eh.wrapfunction(discovery, b'checkheads')
+            def wrapcheckheads(orig, *args, **kwargs):
                 ui.note(b'His head smashed in and his heart cut out')
                 return orig(*args, **kwargs)
         """