From: "Maciej W. Rozycki" <macro@orcam.me.uk>
To: Arnd Bergmann <arnd@arndb.de>,
Thomas Bogendoerfer <tsbogend@alpha.franken.de>
Cc: Huacai Chen <chenhuacai@kernel.org>,
Huacai Chen <chenhuacai@loongson.cn>,
Jiaxun Yang <jiaxun.yang@flygoat.com>,
linux-arch@vger.kernel.org, linux-mips@vger.kernel.org,
linux-kernel@vger.kernel.org
Subject: [PATCH 2/4] div64: Correct inline documentation for `do_div'
Date: Tue, 20 Apr 2021 04:50:33 +0200 (CEST) [thread overview]
Message-ID: <alpine.DEB.2.21.2104200151310.44318@angie.orcam.me.uk> (raw)
In-Reply-To: <alpine.DEB.2.21.2104200044060.44318@angie.orcam.me.uk>
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@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;
* }
*
next prev parent reply other threads:[~2021-04-20 2:50 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2021-04-20 2:50 [PATCH 0/4] Reinstate and improve MIPS `do_div' implementation Maciej W. Rozycki
2021-04-20 2:50 ` [PATCH 1/4] lib/math: Add a `do_div' test module Maciej W. Rozycki
2021-04-20 2:50 ` Maciej W. Rozycki [this message]
2021-04-20 2:50 ` [PATCH 3/4] MIPS: Reinstate platform `__div64_32' handler Maciej W. Rozycki
2021-04-22 18:36 ` Guenter Roeck
2021-04-22 20:43 ` Maciej W. Rozycki
2021-04-20 2:50 ` [PATCH 4/4] MIPS: Avoid DIVU in `__div64_32' is result would be zero Maciej W. Rozycki
2021-04-21 16:05 ` H. Nikolaus Schaller
2021-04-21 16:16 ` Maciej W. Rozycki
2021-04-22 7:56 ` Thomas Bogendoerfer
2021-04-22 9:12 ` Maciej W. Rozycki
2021-04-22 11:08 ` Thomas Bogendoerfer
2021-04-22 20:47 ` Maciej W. Rozycki
2021-04-27 12:16 ` Maciej W. Rozycki
2021-04-22 11:17 ` Andreas Schwab
2021-04-21 12:01 ` [PATCH 0/4] Reinstate and improve MIPS `do_div' implementation Thomas Bogendoerfer
2021-04-21 13:12 ` Maciej W. Rozycki
2021-04-21 16:00 ` H. Nikolaus Schaller
2021-04-21 19:04 ` Maciej W. Rozycki
2021-04-22 5:53 ` H. Nikolaus Schaller
2021-04-22 13:39 ` Jiaxun Yang
2021-04-22 15:58 ` Maciej W. Rozycki
2021-04-22 16:00 ` H. Nikolaus Schaller
2021-04-22 16:55 ` Maciej W. Rozycki
2021-04-22 17:06 ` H. Nikolaus Schaller
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=alpine.DEB.2.21.2104200151310.44318@angie.orcam.me.uk \
--to=macro@orcam.me.uk \
--cc=arnd@arndb.de \
--cc=chenhuacai@kernel.org \
--cc=chenhuacai@loongson.cn \
--cc=jiaxun.yang@flygoat.com \
--cc=linux-arch@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mips@vger.kernel.org \
--cc=tsbogend@alpha.franken.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).