[PATCH 2/7] doc: fix/improve documentation of verdicts

[Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>]

- Include that `reject` behaves like `drop` with respect to ending the
  evaluations of rules (causing later statements to be not executed) and the
  whole ruleset (preventing any further evaluation of any other base chains with
  higher priorities at the same hook or any at later hooks.
- Clarify that a terminating statement also prevents the execution of later
  statements in the same rule and give an example about that.
- Correct that `accept` won’t terminate ruleset (which is generally used for the
  whole set of all chains, rules, etc.) but only that of the current base chain
  respectively any regular ones called from that.
  Indicate that `accept` only accepts the packet from the current base chain’s
  point of view.
  Clarify that not only chains of a later hook could still drop the packet, but
  also ones from the same hook if they have a higher priority.
- With respect to `return`/`jump`/`goto`, remove the “call stack” which seems
  rather an implementation detail and simply mention that the calling position
  is remembered.
  Also don’t use the wording “last chain”, which seems ambiguous. If the called
  chain itself called another chain and evaluation just returned from that, that
  might be misunderstood as the (chronologically) “last” one. “Calling chain”
  should be clear.
  Also don’t use the wording “new chain” (the chain isn’t strictly speaking
  “new”) and some places where merely “chain” was used, with `'CHAIN'` as the
  symbol for the called chain.
- For `return`, more clearly differentiate between the types of chains and added
  the missing description of `return` in a regular chain called via `goto`.
- For `jump`/`goto`, clarify, that their called chains return when a `return`
  verdict is issued *in them* not just when any `return` verdict (for example in
  another sub-chain) is issued.
- For `goto`, I intentionally listed the cases when evaluation does not return
  to the calling case - because I guess it might actually do so, namely when the
  called chain itself explicitly jumps or go(to)es back.
- Various other minor improvements/clarifications to wording.

Link: https://lore.kernel.org/netfilter-devel/3c7ddca7029fa04baa2402d895f3a594a6480a3a.camel@scientia.org/T/#t
Signed-off-by: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
---
 doc/statements.txt | 61 ++++++++++++++++++++++++++++++----------------
 1 file changed, 40 insertions(+), 21 deletions(-)

diff --git a/doc/statements.txt b/doc/statements.txt
index 6226713b..b085b3ab 100644
--- a/doc/statements.txt
+++ b/doc/statements.txt
@@ -10,34 +10,53 @@ ____
 'CHAIN' := 'chain_name' | *{* 'statement' ... *}*
 ____
 
-*accept* and *drop* are absolute verdicts -- they terminate ruleset evaluation immediately.
+*accept* and *drop*/*reject* are absolute verdicts, which immediately terminate
+the evaluation of the current rule, i.e. even any later statements of the
+current rule won’t get executed.
+
+.*counter* will get executed:
+------------------------------
+… counter accept
+------------------------------
+
+.*counter* won’t get executed:
+------------------------------
+… accept counter
+------------------------------
+
+Further:
 
 [horizontal]
-*accept*:: Terminate ruleset evaluation and accept the packet.
-The packet can still be dropped later by another hook, for instance accept
-in the forward hook still allows one to drop the packet later in the postrouting hook,
-or another forward base chain that has a higher priority number and is evaluated
-afterwards in the processing pipeline.
-*drop*:: Terminate ruleset evaluation and drop the packet.
-The drop occurs instantly, no further chains or hooks are evaluated.
-It is not possible to accept the packet in a later chain again, as those
-are not evaluated anymore for the packet.
+*accept*:: Terminate the evaluation of the current base chain (and any regular
+chains called from it) and accept the packet from their point of view.
+The packet may however still be dropped/rejected by another chain with a higher
+priority of the same hook or by any chain of a later hook.
+For example an accept in the forward hook still allows one to drop the packet
+later in the postrouting hook, or another forward base chain that has a higher
+priority number and is evaluated afterwards in the processing pipeline.
+*drop*/*reject*:: Terminate ruleset evaluation and drop/reject the packet. This
+occurs instantly, no further chains of any hooks are evaluated and it is thus
+not possible to again accept the packet in a later chain, as those are not
+evaluated anymore for the packet.
 *queue*:: Terminate ruleset evaluation and queue the packet to userspace.
 Userspace must provide a drop or accept verdict.  In case of accept, processing
 resumes with the next base chain hook, not the rule following the queue verdict.
 *continue*:: Continue ruleset evaluation with the next rule. This
  is the default behaviour in case a rule issues no verdict.
-*return*:: Return from the current chain and continue evaluation at the
- next rule in the last chain. If issued in a base chain, it is equivalent to the
- base chain policy.
-*jump* 'CHAIN':: Continue evaluation at the first rule in 'CHAIN'. The current
- position in the ruleset is pushed to a call stack and evaluation will continue
- there when the new chain is entirely evaluated or a *return* verdict is issued.
- In case an absolute verdict is issued by a rule in the chain, ruleset evaluation
- terminates immediately and the specific action is taken.
-*goto* 'CHAIN':: Similar to *jump*, but the current position is not pushed to the
- call stack, meaning that after the new chain evaluation will continue at the last
- chain instead of the one containing the goto statement.
+*return*:: In a regular chain that was called via *jump*, end evaluation of that
+ chain and return to the calling chain, continuing evaluation there at the rule
+ after the calling rule.
+ In a regular chain that was called via *goto* or in a base chain, the *return*
+ verdict is equivalent to the base chain’s policy.
+*jump* 'CHAIN':: Continue evaluation at the first rule of 'CHAIN'. The position
+ in the current chain is remembered and evaluation will continue there with the
+ next rule when 'CHAIN' is entirely evaluated or a *return* verdict is issued in
+ 'CHAIN' itself.
+ In case an absolute verdict is issued by a rule in 'CHAIN', evaluation
+ terminates as described above.
+*goto* 'CHAIN':: Similar to *jump*, but the position in the current chain is not
+ remembered and evaluation will neihter return at the current chain when 'CHAIN'
+ is entirely evaluated nor when a *return* verdict is issued in 'CHAIN' itself.
 
 An alternative to specifying the name of an existing, regular chain in 'CHAIN'
 is to specify an anonymous chain ad-hoc. Like with anonymous sets, it can't be
-- 
2.51.0