linux-kernel - [PATCH 2/4] div64: Correct inline documentation for `do

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] [thread-next>] [day] [month] [year] [list]

Message-ID: <alpine.DEB.2.21.2104200151310.44318@angie.orcam.me.uk>
Date:   Tue, 20 Apr 2021 04:50:33 +0200 (CEST)
From:   "Maciej W. Rozycki" <macro@...am.me.uk>
To:     Arnd Bergmann <arnd@...db.de>,
        Thomas Bogendoerfer <tsbogend@...ha.franken.de>
cc:     Huacai Chen <chenhuacai@...nel.org>,
        Huacai Chen <chenhuacai@...ngson.cn>,
        Jiaxun Yang <jiaxun.yang@...goat.com>,
        linux-arch@...r.kernel.org, linux-mips@...r.kernel.org,
        linux-kernel@...r.kernel.org
Subject: [PATCH 2/4] div64: Correct inline documentation for `do_div'

Correct inline documentation for `do_div', which is a function-like 
macro the `n' parameter of which has the semantics of a C++ reference: 
it is both read and written in the context of the caller without an 
explicit dereference such as with a pointer.

In the C programming language it has no equivalent for proper functions, 
in terms of which the documentation expresses the semantics of `do_div', 
but substituting a pointer in documentation is misleading, and using the 
C++ notation should at least raise the reader's attention and encourage 
to seek explanation even if the C++ semantics is not readily understood.

While at it observe that "semantics" is an uncountable noun, so refer to 
it with a singular rather than plural verb.

Signed-off-by: Maciej W. Rozycki <macro@...am.me.uk>
---
NB there's a `checkpatch.pl' warning for tabs preceded by spaces, but that 
is just the style of the piece of code quoted and I can see no gain from 
changing it or worse yet making inconsistent.
---
 include/asm-generic/div64.h |   10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

linux-div64-doc-fix.diff
Index: linux-3maxp-div64/include/asm-generic/div64.h
===================================================================
--- linux-3maxp-div64.orig/include/asm-generic/div64.h
+++ linux-3maxp-div64/include/asm-generic/div64.h
@@ -8,12 +8,14 @@
  * Optimization for constant divisors on 32-bit machines:
  * Copyright (C) 2006-2015 Nicolas Pitre
  *
- * The semantics of do_div() are:
+ * The semantics of do_div() is, in C++ notation, observing that the name
+ * is a function-like macro and the n parameter has the semantics of a C++
+ * reference:
  *
- * uint32_t do_div(uint64_t *n, uint32_t base)
+ * uint32_t do_div(uint64_t &n, uint32_t base)
  * {
- * 	uint32_t remainder = *n % base;
- * 	*n = *n / base;
+ * 	uint32_t remainder = n % base;
+ * 	n = n / base;
  * 	return remainder;
  * }
  *