linux-kernel - Re: [PATCH v2] mm/swap.c: make functions and their kernel-doc agree

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Date:   Wed, 31 Jan 2018 14:25:58 +0100
From:   Michal Hocko <mhocko@...nel.org>
To:     Matthew Wilcox <willy@...radead.org>
Cc:     Randy Dunlap <rdunlap@...radead.org>,
        Linux MM <linux-mm@...ck.org>,
        Andrew Morton <akpm@...ux-foundation.org>,
        LKML <linux-kernel@...r.kernel.org>, Jan Kara <jack@...e.cz>
Subject: Re: [PATCH v2] mm/swap.c: make functions and their kernel-doc agree

On Tue 30-01-18 23:58:48, Matthew Wilcox wrote:
> On Tue, Jan 30, 2018 at 01:34:00PM +0100, Michal Hocko wrote:
> > On Mon 29-01-18 16:43:55, Randy Dunlap wrote:
> > > - for function pagevec_lookup_entries(), change the function parameter
> > >   name from nr_pages to nr_entries since that is more descriptive of
> > >   what the parameter actually is and then it matches the kernel-doc
> > >   comments also
> > 
> > I know what is nr_pages because I do expect pages to be returned. What
> > are entries? Can it be something different from pages?
> 
> entries are any page cache entries -- pages or exceptional entries.

Fair point.

> calling this parameter nr_pages tricks you into thinking that you'll
> only get pages back.

Well, the data structure we are using is a pagevec and that operates on
top of struct pages. It is true that this is quite confusing especially
for those who are not familiar with exceptional entries. Hopefully the
associated documentation helps.

-- 
Michal Hocko
SUSE Labs