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 <ma...@orcam.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;
* }
*
