linux-kernel - Re: kernel-doc comment with anonymous macro?

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <f4ec1d06-0579-4484-adbe-5247374c4a57@infradead.org>
Date: Mon, 15 Dec 2025 22:28:35 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: Bagas Sanjaya <bagasdotme@...il.com>,
 Linux Kernel Mailing List <linux-kernel@...r.kernel.org>,
 Linux Virtualization <virtualization@...ts.linux.dev>,
 Linux Documentation <linux-doc@...r.kernel.org>
Cc: "Michael S. Tsirkin" <mst@...hat.com>, Jason Wang <jasowang@...hat.com>,
 Xuan Zhuo <xuanzhuo@...ux.alibaba.com>, Eugenio Pérez
 <eperezma@...hat.com>, Paolo Abeni <pabeni@...hat.com>,
 Jonathan Corbet <corbet@....net>
Subject: Re: kernel-doc comment with anonymous macro?

Hi Bagas--

On 12/15/25 4:13 PM, Bagas Sanjaya wrote:
> Hi,
> 
> ./scripts/kernel-doc reports warning on include/linux/virtio.h:
> 
> Info: include/linux/virtio.h:16 Scanning doc for struct virtqueue
> Info: include/linux/virtio.h:139 Scanning doc for struct virtio_device
> Warning: include/linux/virtio.h:183 struct member 'VIRTIO_DECLARE_FEATURES(features' not described in 'virtio_device'
> Info: include/linux/virtio.h:217 Scanning doc for struct virtio_driver
> Warning: include/linux/virtio.h:183 struct member 'VIRTIO_DECLARE_FEATURES(features' not described in 'virtio_device'
> 1 errors
> 
> struct virtio_device is defined as:
> 
> struct virtio_device {
> 	int index;
> 	bool failed;
> 	bool config_core_enabled;
> 	bool config_driver_disabled;
> 	bool config_change_pending;
> 	spinlock_t config_lock;
> 	spinlock_t vqs_list_lock;
> 	struct device dev;
> 	struct virtio_device_id id;
> 	const struct virtio_config_ops *config;
> 	const struct vringh_config_ops *vringh_config;
> 	const struct virtio_map_ops *map;
> 	struct list_head vqs;
> 	VIRTIO_DECLARE_FEATURES(features);
> 	void *priv;
> 	union virtio_map vmap;
> #ifdef CONFIG_VIRTIO_DEBUG
> 	struct dentry *debugfs_dir;
> 	u64 debugfs_filter_features[VIRTIO_FEATURES_U64S];
> #endif
> };
> 
> where VIRTIO_DECLARE_FEATURES() is an anonymous macro.
> 
> What can I do to fix the warning?

Yeah, I had seen this one also. My only though is to special-case it and then
declare
    union {
	u64 features;
	u64 features_array[];
    };
in kdoc_parser.py. Something similar to what syscall_munge() does there.
I hope that would work but I don't know for sure.

At least one downside to that is that we might end up needing to add special case
after special case ....

I guess we are waiting for the summit/LPC group to read and find time to
respond.

-- 
~Randy