Date:   Wed, 8 Dec 2021 14:56:01 +0100
From:   David Sterba <dsterba@suse.cz>
To:     Randy Dunlap <rdunlap@infradead.org>
Cc:     dsterba@suse.cz, linux-kernel@vger.kernel.org,
        kernel test robot <lkp@intel.com>,
        Naohiro Aota <naohiro.aota@wdc.com>,
        David Sterba <dsterba@suse.com>, Chris Mason <clm@fb.com>,
        Josef Bacik <josef@toxicpanda.com>,
        linux-btrfs@vger.kernel.org, nborisov@suse.com
Subject: Re: [PATCH] btrfs: zoned: convert comment to kernel-doc format
Message-ID: <20211208135601.GJ28560@twin.jikos.cz>
Reply-To: dsterba@suse.cz
Mail-Followup-To: dsterba@suse.cz, Randy Dunlap <rdunlap@infradead.org>,
        linux-kernel@vger.kernel.org, kernel test robot <lkp@intel.com>,
        Naohiro Aota <naohiro.aota@wdc.com>,
        David Sterba <dsterba@suse.com>, Chris Mason <clm@fb.com>,
        Josef Bacik <josef@toxicpanda.com>, linux-btrfs@vger.kernel.org,
        nborisov@suse.com
References: <20211203064820.27033-1-rdunlap@infradead.org>
 <20211207194820.GH28560@twin.jikos.cz>
 <28105cc3-88b0-763d-5bc5-06eb67ee130f@infradead.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <28105cc3-88b0-763d-5bc5-06eb67ee130f@infradead.org>
User-Agent: Mutt/1.5.23.1-rc1 (2014-03-12)
Precedence: bulk

On Tue, Dec 07, 2021 at 04:43:15PM -0800, Randy Dunlap wrote:
> On 12/7/21 11:48, David Sterba wrote:
> > On Thu, Dec 02, 2021 at 10:48:20PM -0800, Randy Dunlap wrote:
> >> Complete kernel-doc notation for btrfs_zone_activate() to prevent
> >> kernel-doc warnings:
> >>
> >> zoned.c:1784: warning: This comment starts with '/**', but isn't a kernel-doc comment. Refer Documentation/doc-guide/kernel-doc.rst
> >>  * Activate block group and underlying device zones
> >> zoned.c:1784: warning: missing initial short description on line:
> >>  * Activate block group and underlying device zones
> > 
> > We've been using a slightly different format than the strict kernel-doc,
> 
> I'm sorry to hear that.

I feels like the kdoc format is meant for generating documentation and
has some requirements that I do not consider too human friendly, like
mandating the function name AND the function description on the first
line no matter how long it is. I'd rather have something for developers
where first line is summary of what the function does and list of
parameters to verify.

> > in this cas the function name is not repeated (because it's right under
> > the comment), what we want is the argument list checks (order and
> > completeness).
> 
> Please just eliminate/prevent the warning then.
> I don't care how it's done.

It used to work and got changed/broken in 52042e2db452 ("scripts:
kernel-doc: validate kernel-doc markup with the actual names"), we
actually wanted to enable kdoc checks by default in our local Makefile.

We were working on that with Nikolay and he asked Mauro if the function
name could be optional. No answer so we get the warnings.