Re: [PATCH net-next v4 2/3] net: ynl: add generated kdoc to UAPI headers

[Donald Hunter]

Oleksij Rempel <o.rempel@xxxxxxxxxxxxxx> writes:

> diff --git a/include/uapi/linux/if_team.h b/include/uapi/linux/if_team.h
> index a5c06243a435..22d68c0dad60 100644
> --- a/include/uapi/linux/if_team.h
> +++ b/include/uapi/linux/if_team.h
> @@ -12,6 +12,12 @@
>  #define TEAM_STRING_MAX_LEN			32
>  #define TEAM_GENL_CHANGE_EVENT_MC_GRP_NAME	"change_event"
>  
> +/*
> + * The team nested layout of get/set msg looks like [TEAM_ATTR_LIST_OPTION]
> + * [TEAM_ATTR_ITEM_OPTION] [TEAM_ATTR_OPTION_*], ... [TEAM_ATTR_ITEM_OPTION]
> + * [TEAM_ATTR_OPTION_*], ... ... [TEAM_ATTR_LIST_PORT] [TEAM_ATTR_ITEM_PORT]
> + * [TEAM_ATTR_PORT_*], ... [TEAM_ATTR_ITEM_PORT] [TEAM_ATTR_PORT_*], ... ...
> + */

That's a really unfortunate result of word wrapping the doc string from
team.yaml

I wonder if it's possible to recognise literal doc strings, with
embedded newlines and emit them line by line. That would require adding
the | symbol to the doc string in team.yaml, like this:

    doc: |
      The team nested layout of get/set msg looks like
          [TEAM_ATTR_LIST_OPTION]
              [TEAM_ATTR_ITEM_OPTION]
                  [TEAM_ATTR_OPTION_*], ...
              [TEAM_ATTR_ITEM_OPTION]
                  [TEAM_ATTR_OPTION_*], ...
              ...
          [TEAM_ATTR_LIST_PORT]
              [TEAM_ATTR_ITEM_PORT]
                  [TEAM_ATTR_PORT_*], ...
              [TEAM_ATTR_ITEM_PORT]
                  [TEAM_ATTR_PORT_*], ...
              ...

Sure, you might occasionally get some messy line wrapping but I think
that's better than flowing literal blocks of text.

>  enum {
>  	TEAM_ATTR_UNSPEC,
>  	TEAM_ATTR_TEAM_IFINDEX,
> @@ -30,6 +36,11 @@ enum {
>  	TEAM_ATTR_ITEM_OPTION_MAX = (__TEAM_ATTR_ITEM_OPTION_MAX - 1)
>  };
>