]> git.ipfire.org Git - thirdparty/knot-resolver.git/commitdiff
doc: use :any: to refer to non-function policies
authorTomas Krizek <tomas.krizek@nic.cz>
Fri, 11 Dec 2020 14:42:22 +0000 (15:42 +0100)
committerTomas Krizek <tomas.krizek@nic.cz>
Fri, 11 Dec 2020 14:56:36 +0000 (15:56 +0100)
:func: directive automatically always adds brackets. This results in
links such as "policy.PASS()", which can be confusing, since the actual
policy is supposed to be "policy.PASS".

Using :any: results in links without the added brackets, which makes
non-function policies less confusing.

modules/hints/README.rst
modules/policy/README.rst

index def8d24a43f224ea8e331d2738cfb22b6490b21e..65bebaa164eed56acbbf3b2e275c8e2ec2032cdf 100644 (file)
@@ -33,7 +33,7 @@ Examples
     hints['foo.bar'] = '127.0.0.1'
 
 .. note:: The :ref:`policy <mod-policy>` module applies before hints, meaning e.g. that hints for special names (:rfc:`6761#section-6`) like ``localhost`` or ``test`` will get shadowed by policy rules by default.
-    That can be worked around e.g. by explicit ``policy.PASS`` action.
+    That can be worked around e.g. by explicit :any:`policy.PASS` action.
 
 Properties
 ----------
index dbcc5064d6f1471c9328b6ffcd87f7ed39b87d48..8d4a7f0642cd36d65a6072e57ee913631378a5a0 100644 (file)
@@ -13,11 +13,11 @@ This module can block, rewrite, or alter inbound queries based on user-defined p
 
 Each policy *rule* has two parts: a *filter* and an *action*. A *filter* selects which queries will be affected by the policy, and *action* which modifies queries matching the associated filter.
 
-Typically a rule is defined as follows: ``filter(action(action parameters), filter parameters)``. For example, a filter can be ``suffix`` which matches queries whose suffix part is in specified set, and one of possible actions is ``DENY``, which denies resolution. These are combined together into ``policy.suffix(policy.DENY, {todname('badguy.example.')})``. The rule is effective when it is added into rule table using ``policy.add()``, please see examples below.
+Typically a rule is defined as follows: ``filter(action(action parameters), filter parameters)``. For example, a filter can be ``suffix`` which matches queries whose suffix part is in specified set, and one of possible actions is :any:`policy.DENY`, which denies resolution. These are combined together into ``policy.suffix(policy.DENY, {todname('badguy.example.')})``. The rule is effective when it is added into rule table using ``policy.add()``, please see examples below.
 
 This module is enabled by default because it implements mandatory :rfc:`6761` logic.
 When no rule applies to a query, built-in rules for `special-use <https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml>`_ and `locally-served <http://www.iana.org/assignments/locally-served-dns-zones>`_ domain names are applied.
-These rules can be overriden by action :func:`policy.PASS`.  For debugging purposes you can also add ``modules.unload('policy')`` to your config to unload the module.
+These rules can be overriden by action :any:`policy.PASS`.  For debugging purposes you can also add ``modules.unload('policy')`` to your config to unload the module.
 
 
 Filters
@@ -80,7 +80,7 @@ It is also possible to define custom filter function with any name.
    end
 
 This custom filter can be used as any other built-in filter.
-For example this applies our custom filter and executes action :func:`policy.DENY` on all queries of type `HINFO`:
+For example this applies our custom filter and executes action :any:`policy.DENY` on all queries of type `HINFO`:
 
 .. code-block:: lua
 
@@ -221,7 +221,7 @@ Following actions act on request and then processing continue until first non-ch
 
 .. py:data:: DEBUG_CACHE_MISS
 
-   Enable extra verbose logging but print logs only for requests which required information which was not available locally (i.e. requests which forced resolver to communicate over network). Intended usage is for debugging problems with remote servers. This action typically produces less logs than :func:`policy.DEBUG_ALWAYS` but all caveats from :func:`policy.DEBUG_IF` apply as well.
+   Enable extra verbose logging but print logs only for requests which required information which was not available locally (i.e. requests which forced resolver to communicate over network). Intended usage is for debugging problems with remote servers. This action typically produces less logs than :any:`policy.DEBUG_ALWAYS` but all caveats from :func:`policy.DEBUG_IF` apply as well.
 
    .. code-block:: lua
 
@@ -567,20 +567,20 @@ Response policy zones
   .. csv-table::
    :header: "RPZ Right Hand Side", "Knot Resolver Action", "BIND Compatibility"
 
-   "``.``", "``action`` is used", "compatible if ``action`` is :func:`policy.DENY`"
+   "``.``", "``action`` is used", "compatible if ``action`` is :any:`policy.DENY`"
    "``*.``", ":func:`policy.ANSWER`", "yes"
-   "``rpz-passthru.``", ":func:`policy.PASS`", "yes"
-   "``rpz-tcp-only.``", ":func:`policy.TC`", "yes"
-   "``rpz-drop.``", ":func:`policy.DROP`", "no [#]_"
+   "``rpz-passthru.``", ":any:`policy.PASS`", "yes"
+   "``rpz-tcp-only.``", ":any:`policy.TC`", "yes"
+   "``rpz-drop.``", ":any:`policy.DROP`", "no [#]_"
    "fake A/AAAA", ":func:`policy.ANSWER`", "yes"
    "fake CNAME", "not supported", "no"
 
-  .. [#] Our :func:`policy.DROP` returns *SERVFAIL* answer (for historical reasons).
+  .. [#] Our :any:`policy.DROP` returns *SERVFAIL* answer (for historical reasons).
 
 
 .. function:: rpz(action, path, [watch = true])
 
-  :param action: the default action for match in the zone; typically you want :func:`policy.DENY`
+  :param action: the default action for match in the zone; typically you want :any:`policy.DENY`
   :param path: path to zone file
   :param watch: boolean, if true, the file will be reloaded on file change