On Wed, 14 Jun 2023 22:11:38 +0000 Kubalewski, Arkadiusz wrote:
> Thanks for pointing this, but it doesn't work :/
>
> I tried described format but still ./scripts/kernel-doc warns about it.
> Same as 'make htmldocs' does, as it uses ./scripts/kernel-doc
>
> Also, if the enum is not described in the header, the docs produced by
> the 'make htmldocs' would list the enum with the comment "undescribed".
Oh, you're right :S Looks like private: does not work for enums.
> It seems we need fixing:
> - prevent warning from ./scripts/kernel-doc, so enums marked as "private:"
> would not warn
> - generate __<ENUM_NAME>_MAX while marking them as "/* private: */"
> - add some kind of "pattern exclude" directive/mechanics for generating
> docs with sphinx
>
> Does it make sense?
> TBH, not yet sure if all above are possible..
Let's ask Jon, and wait for him to chime in, I don't think these
warnings should be a blocker for new families.
Jon, we have some "meta" entries in the uAPI enums in netlink
to mark the number of attributes, eg:
enum {
NETDEV_A_DEV_IFINDEX = 1,
NETDEV_A_DEV_PAD,
NETDEV_A_DEV_XDP_FEATURES,
/* private: */
__NETDEV_A_DEV_MAX, // this
NETDEV_A_DEV_MAX = (__NETDEV_A_DEV_MAX - 1) // and this
};
Also masks of all flags like:
enum netdev_xdp_act {
NETDEV_XDP_ACT_BASIC = 1,
NETDEV_XDP_ACT_REDIRECT = 2,
NETDEV_XDP_ACT_NDO_XMIT = 4,
NETDEV_XDP_ACT_XSK_ZEROCOPY = 8,
NETDEV_XDP_ACT_HW_OFFLOAD = 16,
NETDEV_XDP_ACT_RX_SG = 32,
NETDEV_XDP_ACT_NDO_XMIT_SG = 64,
/* private: */
NETDEV_XDP_ACT_MASK = 127, // this
};
which user space should not care about.
I was hoping we can mark them as /* private: */ but that doesn't
work, when we add kdocs without documenting those - there's a warning.
Is this a known problem? Is it worth fixing?
Do we need to fix both kernel-doc and sphinx or just the former?
