Re: [PATCH net-next v3 0/8] ethtool: generate uapi header from the spec

[Jakub Kicinski]

On Mon, 2 Dec 2024 21:07:38 -0800 Stanislav Fomichev wrote:
> diff --git a/Documentation/netlink/specs/ethtool.yaml b/Documentation/netlink/specs/ethtool.yaml
> index efa00665c191..859ae0cb1fd8 100644
> --- a/Documentation/netlink/specs/ethtool.yaml
> +++ b/Documentation/netlink/specs/ethtool.yaml
> @@ -60,7 +60,8 @@ uapi-header: linux/ethtool_netlink_generated.h
>      name-prefix: ethtool-c33-pse-ext-state-
>      header: linux/ethtool.h
>      entries:
> -        - none
> +        - name: none
> +          doc: none
> 
> The first one fixes the bullet list (seems like mixing entries with and
> without docs confuses ynl-gen-rst.py). 

Ah, yes, that makes sense, either all entries should be objects or all
should be strings. I will spare you trying to figure out how to enforce
that in jsonschema :)

nit: "-" and "name: none" on separate lines

>          -
>            name: error-condition
>            doc: Group of error_condition states
> @@ -875,15 +876,15 @@ uapi-header: linux/ethtool_netlink_generated.h
>          value: 0
>        -
>          name: pair
> -        doc: ETHTOOL_A_CABLE_PAIR_
> +        doc: ETHTOOL_A_CABLE_PAIR
>          type: u8
>        -
>          name: code
> -        doc: ETHTOOL_A_CABLE_RESULT_CODE_
> +        doc: ETHTOOL_A_CABLE_RESULT_CODE
>          type: u8
>        -
>          name: src
> -        doc: ETHTOOL_A_CABLE_INF_SRC_
> +        doc: ETHTOOL_A_CABLE_INF_SRC
>          type: u32
>    -
>      name: cable-fault-length
>
> And removing trailing _ fixes the rest (don't know why).

Mmm. Trailing _ must mean something in ReST.
Can't decide now whether we care more about supporting ReST formatting
in YAML docs or protecting unsuspecting developers from this sort of a
surprise. So let's do the easier thing for now.

> Any objections to folding it as is into v4? I can go on and try to
> understand why ynl-gen-rst.py behaves exactly that way, but not sure
> it would buy us anything?

Yup, v4 with more or less the diff above SGTM!