linux-kernel - Re: [PATCH 3/6] timekeeping: add kernel-doc markup for pvclock notifier

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 for Android: free password hash cracker in your pocket

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

Message-ID: <87zh3i45mt.fsf@nanos.tec.linutronix.de>
Date:   Sun, 15 Nov 2020 23:28:10 +0100
From:   Thomas Gleixner <tglx@...utronix.de>
To:     Alex Shi <alex.shi@...ux.alibaba.com>, john.stultz@...aro.org
Cc:     Stephen Boyd <sboyd@...nel.org>, linux-kernel@...r.kernel.org
Subject: Re: [PATCH 3/6] timekeeping: add kernel-doc markup for pvclock notifier

On Fri, Nov 13 2020 at 15:24, Alex Shi wrote:
>  /**
>   * pvclock_gtod_register_notifier - register a pvclock timedata update listener
> + * @nb: a notifier entry which register on pvclock_gtod_chain.

What is a notifier entry? The struct is named notifier_block and the
argument is a pointer to a notifier block. So why making things up?

Also it's completely irrelevant for the reader to know about the name of
the notifier chain. The function documentation says:

         register a pvclock timedata update listener

which precisely describes what the function does. pvclock_gtod_chain is
an internal implementation detail and nothing external can depend on it.
It could be renamed to 'foo_bar' and the function would still do the
same thing.

* @nb: Notifier block to register

is precise and good enough, isn't it?

Thanks,

        tglx