From patchwork Tue Apr 20 02:50:33 2021 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Maciej W. Rozycki" X-Patchwork-Id: 12213217 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-15.3 required=3.0 tests=BAYES_00, HEADER_FROM_DIFFERENT_DOMAINS,INCLUDES_CR_TRAILER,INCLUDES_PATCH, MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS,USER_AGENT_SANE_1 autolearn=ham autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 22BABC433B4 for ; Tue, 20 Apr 2021 02:50:36 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 00ADE60FE6 for ; Tue, 20 Apr 2021 02:50:35 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S229694AbhDTCvF (ORCPT ); Mon, 19 Apr 2021 22:51:05 -0400 Received: from lindbergh.monkeyblade.net ([23.128.96.19]:39314 "EHLO lindbergh.monkeyblade.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S229508AbhDTCvE (ORCPT ); Mon, 19 Apr 2021 22:51:04 -0400 Received: from angie.orcam.me.uk (angie.orcam.me.uk [IPv6:2001:4190:8020::4]) by lindbergh.monkeyblade.net (Postfix) with ESMTP id 3D8F6C06174A; Mon, 19 Apr 2021 19:50:34 -0700 (PDT) Received: by angie.orcam.me.uk (Postfix, from userid 500) id 8B4E79200BB; Tue, 20 Apr 2021 04:50:33 +0200 (CEST) Received: from localhost (localhost [127.0.0.1]) by angie.orcam.me.uk (Postfix) with ESMTP id 846FD9200B4; Tue, 20 Apr 2021 04:50:33 +0200 (CEST) Date: Tue, 20 Apr 2021 04:50:33 +0200 (CEST) From: "Maciej W. Rozycki" To: Arnd Bergmann , Thomas Bogendoerfer cc: Huacai Chen , Huacai Chen , Jiaxun Yang , 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' In-Reply-To: Message-ID: References: User-Agent: Alpine 2.21 (DEB 202 2017-01-01) MIME-Version: 1.0 Precedence: bulk List-ID: X-Mailing-List: linux-mips@vger.kernel.org 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 --- 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; * } *