Re: [PATCH v3 1/2] include/linux/watch_queue: Improve documentation

[David Howells]

Siddh Raman Pant <code@xxxxxxxx> wrote:

> +/**
> + * struct watch_type_filter - Filter on watch type
> + *
> + * @type: Type of watch_notification
> + * @subtype_filter: Bitmask of subtypes to filter on
> + * @info_filter: Filter on watch_notification::info
> + * @info_mask: Mask of relevant bits in info_filter
> + */
>  struct watch_type_filter {
>  	enum watch_notification_type type;
> -	__u32		subtype_filter[1];	/* Bitmask of subtypes to filter on */
> -	__u32		info_filter;		/* Filter on watch_notification::info */
> -	__u32		info_mask;		/* Mask of relevant bits in info_filter */
> +	__u32		subtype_filter[1];
> +	__u32		info_filter;
> +	__u32		info_mask;
>  };

Please don't.

The structure is documented fully here:

	Documentation/core-api/watch_queue.rst

See:

	https://docs.kernel.org/core-api/watch_queue.html#event-filtering

The three column approach is much more readable in the code as it doesn't
separate the descriptions from the things described.  Putting things in
columns has been around for around 6000 years.

David