internal-doc: document the config register mechanism stable

internal-doc: document the config register mechanism

This explains the various usage and feature of the config register introduced
in Mercurial 4.3 and 4.4.

--- a/contrib/wix/help.wxs	Fri Oct 27 21:43:22 2017 +0200
+++ b/contrib/wix/help.wxs	Fri Oct 27 18:19:07 2017 +0200
@@ -42,6 +42,7 @@
             <File Id="internals.bundles.txt"      Name="bundles.txt" KeyPath="yes" />
             <File Id="internals.censor.txt"       Name="censor.txt" />
             <File Id="internals.changegroups.txt" Name="changegroups.txt" />
+            <File Id="internals.config.txt"       Name="config.txt" />
             <File Id="internals.requirements.txt" Name="requirements.txt" />
             <File Id="internals.revlogs.txt"      Name="revlogs.txt" />
             <File Id="internals.wireprotocol.txt" Name="wireprotocol.txt" />

--- a/mercurial/help.py	Fri Oct 27 21:43:22 2017 +0200
+++ b/mercurial/help.py	Fri Oct 27 18:19:07 2017 +0200
@@ -202,6 +202,8 @@
      loaddoc('censor', subdir='internals')),
     (['changegroups'], _('Changegroups'),
      loaddoc('changegroups', subdir='internals')),
+    (['config'], _('Config Register'),
+     loaddoc('config', subdir='internals')),
     (['requirements'], _('Repository Requirements'),
      loaddoc('requirements', subdir='internals')),
     (['revlogs'], _('Revision Logs'),

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mercurial/help/internals/config.txt	Fri Oct 27 18:19:07 2017 +0200
@@ -0,0 +1,108 @@
+All config options used within Mercurial should be registered.
+
+Config Option in Core
+=====================
+
+Config options used by Mercurial core are registered in the
+``mercurial.configitems`` module.
+
+Simple entry
+------------
+
+A registration entry typically looks like::
+
+    coreconfigitem('section', 'option',
+        default=MyDefaultValue,
+    )
+
+Once registered, Mercurial will know that ``section.option`` is a legitimate
+config option and that ``MyDefaultValue`` should be used if no other values are
+defined in configuration files.
+
+Complex default value
+---------------------
+
+If the default provided is a callable, it is called to retrieve the default
+value when accessing the config option. This is useful for default value that
+are mutable like the empty list::
+
+    coreconfigitem('pager', 'ignore',
+        default=list,
+    )
+
+In addition, there are cases where the default is not fixed, but computed from
+other properties. In this case, use the ``dynamicdefault`` object as value for
+the ``default`` parameters. A default value is then explicitly required when
+reading the option::
+
+    # registration
+    coreconfigitem('web', 'name',
+        default=dynamicdefault,
+    )
+
+    # usage
+    ui.config('web', 'name', dirnam)
+
+Free form options
+-----------------
+
+Some config sections use free form options (e.g. ``paths``). You can register
+them using the ``generic`` parameters::
+
+    coreconfigitem('paths', '.*',
+        default=None,
+        generic=True,
+    )
+
+When ``generic=True`` is set, the option name is matched as a regular expression
+(rooted to string start). It can be used to select specific sub parameters::
+
+    coreconfigitem('merge-tools', br'.*\.args$',
+        default="$local $base $other",
+        generic=True,
+        priority=-1,
+    )
+
+The ``priority`` parameter control the order used to match the generic pattern
+(lower first).
+
+Config Option in Extensions
+===========================
+
+General case
+------------
+
+Extensions should register config items through the ``registrar`` API (also used
+for commands and others)::
+
+    configtable = {}
+    configitem = registrar.configitem(configtable)
+
+    configitem('blackbox', 'dirty',
+        default=False,
+    )
+
+The ``dynamicdefault`` object is then available as
+``configitem.dynamicdefault``.
+
+Supporting older version
+------------------------
+
+The register was introduced in Mercurial 4.3, the ``generic`` parameter was
+introduced in 4.4. Starting with Mercurial 4.4, all core options were registered
+and developer warnings are emitted when accessing unregistered option.
+
+Extensions supporting version older than Mercurial-4.3 cannot rely on the
+default value registered. The simplest way to register option while still
+supporting older version is to use ``dynamicdefault`` for option requiring a
+default value. The existing code passing an explicit default can then stay in
+use until compatibility to Mercurial 4.2 is dropped.
+
+As reminder here are the default value for each config types:
+- config:      None
+- configbool:  False
+- configbytes: 0
+- configdate:  None
+- configint:   None
+- configlist:  []
+- configpath: None

--- a/tests/test-help.t	Fri Oct 27 21:43:22 2017 +0200
+++ b/tests/test-help.t	Fri Oct 27 18:19:07 2017 +0200
@@ -980,6 +980,7 @@
        bundles       Bundles
        censor        Censor
        changegroups  Changegroups
+       config        Config Register
        requirements  Repository Requirements
        revlogs       Revision Logs
        wireprotocol  Wire Protocol
@@ -3054,6 +3055,13 @@
   Changegroups
   </td></tr>
   <tr><td>
+  <a href="/help/internals.config">
+  config
+  </a>
+  </td><td>
+  Config Register
+  </td></tr>
+  <tr><td>
   <a href="/help/internals.requirements">
   requirements
   </a>