Received-SPF: softfail (google.com: domain of transitioning linux-kernel-owner@vger.kernel.org does not designate 23.128.96.19 as permitted sender) client-ip=23.128.96.19;
Date:   Mon, 28 Mar 2022 23:10:34 +0100
From:   Matthew Wilcox <willy@infradead.org>
To:     Hugh Dickins <hughd@google.com>
Cc:     Stephen Rothwell <sfr@canb.auug.org.au>,
        Andrew Morton <akpm@linux-foundation.org>,
        Vlastimil Babka <vbabka@suse.cz>, linux-kernel@vger.kernel.org,
        linux-next@vger.kernel.org, linux-mm@kvack.org
Subject: Re: linux-next: build warnings after merge of the akpm-current tree
Message-ID: <YkIyWqOAiAmJ4ear@casper.infradead.org>
References: <20220209170245.08968c92@canb.auug.org.au>
 <20220324182725.63a454e3@canb.auug.org.au>
 <224c2147-36fe-93ed-41a5-a4609b59b4a2@google.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <224c2147-36fe-93ed-41a5-a4609b59b4a2@google.com>
Precedence: bulk

On Mon, Mar 28, 2022 at 12:54:14PM -0700, Hugh Dickins wrote:
> On Thu, 24 Mar 2022, Stephen Rothwell wrote:
> 
> > Hi all,
> > 
> > On Wed, 9 Feb 2022 17:02:45 +1100 Stephen Rothwell <sfr@canb.auug.org.au> wrote:
> > > 
> > > After merging the akpm-current tree, today's linux-next build (htmldocs)
> > > produced these warnings:
> > > 
> > > include/linux/mm_types.h:272: warning: Function parameter or member '__filler' not described in 'folio'
> > > include/linux/mm_types.h:272: warning: Function parameter or member 'mlock_count' not described in 'folio'
> > > 
> > > Introduced by commit
> > > 
> > >   60a5c5ab0ba7 ("mm/munlock: maintain page->mlock_count while unevictable")
> > 
> > I am still getting these warnings.  That commit is now
> > 
> >   07ca76067308 ("mm/munlock: maintain page->mlock_count while unevictable")
> > 
> > in Linus' tree :-(
> 
> Sorry about that Stephen: back in Feb I expected Matthew to have strong
> feelings about it, and it wouldn't have been helpful for me to mess it
> around at that time.
> 
> But I'll reply to this now with my suggested patch: which Matthew may
> not like (he may consider it a retrograde step), but unless he NAKs it
> and comes up with something we all like better, it should do for now.

Sorry!  I didn't see these emails back in February, or I would have
fixed it up.  I'm doing a build now, but it's a very slow process
(and seems to have become single-threaded since the last time I ran it?)
so it will be a little while before I can produce a patch.

> I did try to 'make htmldocs' for the first time, but was put off by all
> the new packages I was asked to install - not a good use of time.  And
> I'm so ignorant that I do not even know if "/* public: */" is a helpful
> comment or a special annotation.

Fortunately the documentation is actually documented:
Documentation/doc-guide/kernel-doc.rst
''Structure, union, and enumeration documentation''

There are still many, many warnings when building the documentation, so
don't feel particularly bad about this.  I've tried to make it more
obvious to non-doc-specialists by making W=1 emit warnings, but that
only happens for .c files, not for .h files.  As you say, the amount
of tooling that needs to be installed to make htmldocs is intimidating.