Re: [net-next,v7,5/5] doc/netlink: nftables: Fill out operation attributes

[Jakub Kicinski <kuba@kernel.org>]

This is an AI-generated review of your patch. The human sending this
email has considered the AI review valid, or at least plausible.

For local reproduction steps see https://netdev-ai.bots.linux.dev/ai-local.html
---
doc/netlink: nftables: Fill out operation attributes

This commit fills out the operation attributes for 31 nftables netlink
operations, documenting which attributes are used in request and reply
messages based on kernel implementation.

> diff --git a/Documentation/netlink/specs/nftables.yaml b/Documentation/netlink/specs/nftables.yaml
> index ced567e7a521..5a9d8727a8cb 100644
> --- a/Documentation/netlink/specs/nftables.yaml
> +++ b/Documentation/netlink/specs/nftables.yaml

[ ... ]

> @@ -1612,7 +1626,23 @@ operations:
>          request:
>            value: 0xa03
>            attributes:
> +            # Mentioned in nf_tables_newchain()
> +            - table
> +            - handle
> +            - policy
> +            - flags
> +            # Mentioned in nf_tables_updchain()
> +            - hook
>              - name
> +            - counters
> +            - policy
> +            # Mentioned in nf_tables_addchain()
> +            - hook
> +            - name
> +            - counters
> +            - userdata
> +            # Mentioned in nft_chain_parse_hook()
> +            - type

Does this attribute list contain duplicates? The list shows:
- 'policy' twice (lines 1632 and 1638)
- 'hook' twice (lines 1635 and 1640)
- 'name' twice (lines 1636 and 1641)
- 'counters' twice (lines 1637 and 1642)

While the comments indicate these attributes are referenced by different
kernel functions, the YAML specification should document the unified netlink
interface where each attribute appears at most once per message. Having
duplicates may confuse code generation tools that parse this specification.

Should each attribute be listed only once, with implementation details
documented separately if needed?

[ ... ]

> @@ -1717,7 +1798,24 @@ operations:
>          request:
>            value: 0xa09
>            attributes:
> +            # Mentioned in nf_tables_newset()
> +            - table
>              - name
> +            - key-len
> +            - id
> +            - key-type
> +            - key-len
> +            - flags
> +            - data-type
> +            - data-len
> +            - obj-type
> +            - timeout
> +            - gc-interval
> +            - policy
> +            - desc
> +            - table
> +            - name
> +            - userdata

Are there duplicates in this attribute list? Looking at the newset
operation's request attributes:
- 'table' appears twice (lines 1802 and 1816)
- 'name' appears twice (lines 1803 and 1817)
- 'key-len' appears twice (lines 1804 and 1807)

In netlink messages, attributes are identified by their type ID, and each
should appear at most once in the specification. Should these duplicates
be removed?