Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Organization: Red Hat UK Ltd. Registered Address: Red Hat UK Ltd, Amberley
        Place, 107-111 Peascod Street, Windsor, Berkshire, SI4 1TE, United
        Kingdom.
        Registered in England and Wales under Company Registration No. 3798903
From:   David Howells <dhowells@redhat.com>
In-Reply-To: <97ce37e2fdcfbed29d9467057f0f870359d88b89.1673173920.git.code@siddh.me>
References: <97ce37e2fdcfbed29d9467057f0f870359d88b89.1673173920.git.code@siddh.me> <cover.1673173920.git.code@siddh.me>
To:     Siddh Raman Pant <code@siddh.me>
Cc:     dhowells@redhat.com, Mauro Carvalho Chehab <mchehab@kernel.org>,
        Randy Dunlap <rdunlap@infradead.org>,
        Jonathan Corbet <corbet@lwn.net>,
        "Fabio M. De Francesco" <fmdefrancesco@gmail.com>,
        Eric Dumazet <edumazet@google.com>,
        Christophe JAILLET <christophe.jaillet@wanadoo.fr>,
        Eric Biggers <ebiggers@kernel.org>,
        keyrings <keyrings@vger.kernel.org>,
        linux-security-module <linux-security-module@vger.kernel.org>,
        linux-fsdevel <linux-fsdevel@vger.kernel.org>,
        linux-kernel <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH v3 1/2] include/linux/watch_queue: Improve documentation
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-ID: <2121104.1673359772.1@warthog.procyon.org.uk>
Date:   Tue, 10 Jan 2023 14:09:32 +0000
Message-ID: <2121105.1673359772@warthog.procyon.org.uk>
Precedence: bulk

Siddh Raman Pant <code@siddh.me> 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