Re: [PATCH v5 2/6] doc/netlink: nftables: Add definitions

[Donald Hunter <donald.hunter@gmail.com>]

"Remy D. Farley" <one-d-wide@protonmail.com> writes:

> New enums/flags:
> - payload-base
> - range-ops
> - registers
> - numgen-types
> - log-level
> - log-flags
>
> Added missing enumerations:
> - bitwise-ops
>
> Annotated with a doc comment:
> - bitwise-ops
>
> Signed-off-by: Remy D. Farley <one-d-wide@protonmail.com>
> ---
>  Documentation/netlink/specs/nftables.yaml | 147 +++++++++++++++++++++-
>  1 file changed, 144 insertions(+), 3 deletions(-)
>
> diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
> index cce88819b..e0c25af1d 100644
> --- a/Documentation/netlink/specs/nftables.yaml
> +++ b/Documentation/netlink/specs/nftables.yaml
> @@ -66,9 +66,23 @@ definitions:
>      name: bitwise-ops
>      type: enum
>      entries:
> -      - bool
> -      - lshift
> -      - rshift
> +      -
> +        name: mask-xor  # aka bool (old name)
> +        doc: |
> +          mask-and-xor operation used to implement NOT, AND, OR and XOR
> +            dreg = (sreg & mask) ^ xor
> +          with these mask and xor values:
> +                    mask    xor
> +            NOT:    1       1
> +            OR:     ~x      x
> +            XOR:    1       x
> +            AND:    x       0

This does not render acceptably in the HTML docs and it deviates from
the way the text is presented in nf_tables.h - the description makes
sense in the context of the expression defined by expr-bitwise-attrs
which bitwise-ops is part of.

I suggest moving the doc to expr-bitwise-attrs, which has the advantage
that the ynl doc generator already handles preformatted text for attr
sets.

This diff should be sufficient; note the :: and block indentation:

diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
index 136b2502a811..23106a68512f 100644
--- a/Documentation/netlink/specs/nftables.yaml
+++ b/Documentation/netlink/specs/nftables.yaml
@@ -68,15 +68,9 @@ definitions:
     entries:
       -
         name: mask-xor  # aka bool (old name)
-        doc: |
-          mask-and-xor operation used to implement NOT, AND, OR and XOR
-            dreg = (sreg & mask) ^ xor
-          with these mask and xor values:
-                    mask    xor
-            NOT:    1       1
-            OR:     ~x      x
-            XOR:    1       x
-            AND:    x       0
+        doc: >-
+          mask-and-xor operation used to implement NOT, AND, OR and XOR boolean
+          operations
       # Spinx docutils display warning when interleaving attrsets with strings
       - name: lshift
       - name: rshift
@@ -1014,6 +1008,22 @@ attribute-sets:
         nested-attributes: hook-dev-attrs
   -
     name: expr-bitwise-attrs
+    doc: |
+      The bitwise expression supports boolean and shift operations. It
+      implements the boolean operations by performing the following
+      operation::
+
+          dreg = (sreg & mask) ^ xor
+
+          with these mask and xor values:
+
+          op      mask    xor
+          ----    ----    ---
+          NOT:     1       1
+          OR:     ~x       x
+          XOR:     1       x
+          AND:     x       0
+
     attributes:
       -
         name: sreg