kernel-doc comment with anonymous macro?

kernel-doc comment with anonymous macro?

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 1338 bytes --]

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?

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: kernel-doc comment with anonymous macro?

[Randy Dunlap]

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