From patchwork Tue Dec 1 12:08:53 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Mauro Carvalho Chehab X-Patchwork-Id: 11942767 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=-11.8 required=3.0 tests=BAYES_00,DKIM_INVALID, DKIM_SIGNED,INCLUDES_PATCH,MAILING_LIST_MULTI,SPF_HELO_NONE,SPF_PASS, USER_AGENT_GIT 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 B0AE1C64E7B for ; Tue, 1 Dec 2020 12:09:20 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id 1C1342220B for ; Tue, 1 Dec 2020 12:09:19 +0000 (UTC) Authentication-Results: mail.kernel.org; dkim=fail reason="signature verification failed" (1024-bit key) header.d=kernel.org header.i=@kernel.org header.b="eqagvTWu" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 1C1342220B Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=kernel.org Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=owner-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix) id 6A6FB8D0002; Tue, 1 Dec 2020 07:09:18 -0500 (EST) Received: by kanga.kvack.org (Postfix, from userid 40) id 5E7F38D0007; Tue, 1 Dec 2020 07:09:18 -0500 (EST) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 3C4078D0002; Tue, 1 Dec 2020 07:09:18 -0500 (EST) X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0092.hostedemail.com [216.40.44.92]) by kanga.kvack.org (Postfix) with ESMTP id 106328D0001 for ; Tue, 1 Dec 2020 07:09:18 -0500 (EST) Received: from smtpin09.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay04.hostedemail.com (Postfix) with ESMTP id BE3701F0A for ; Tue, 1 Dec 2020 12:09:17 +0000 (UTC) X-FDA: 77544593154.09.prose67_3310d0f273aa Received: from filter.hostedemail.com (10.5.16.251.rfc1918.com [10.5.16.251]) by smtpin09.hostedemail.com (Postfix) with ESMTP id 9E813180AD811 for ; Tue, 1 Dec 2020 12:09:17 +0000 (UTC) X-HE-Tag: prose67_3310d0f273aa X-Filterd-Recvd-Size: 7153 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by imf35.hostedemail.com (Postfix) with ESMTP for ; Tue, 1 Dec 2020 12:09:16 +0000 (UTC) Received: from mail.kernel.org (ip5f5ad5d9.dynamic.kabel-deutschland.de [95.90.213.217]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id 66E8D221FD; Tue, 1 Dec 2020 12:09:15 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1606824555; bh=CKU7nFOSsbN/XW/BnFcmO1V7GANr6/4MKPOejaVqscI=; h=From:To:Cc:Subject:Date:From; b=eqagvTWutTLcVFzb95Ciee9q0qDa5UFPbM5AAbFexOp5sfH7FAIDQn0oGeWvCXuev TL7qtQMzvXDryh4IscT9uizp2JYQMu8M7zg6S2cpSqSmJfU9hbX12hd/de4h/liUaU ksZGda6OQGzAGoKB9pYow+AqPj198CvdI0OsA+3E= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kk4T2-00DGcs-P1; Tue, 01 Dec 2020 13:09:12 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Alexander Viro , Alexandre Bounine , Andy Lutomirski , Anton Vorontsov , Ben Segall , Colin Cross , Daniel Bristot de Oliveira , Dietmar Eggemann , Evgeniy Polyakov , Ingo Molnar , Juri Lelli , Kees Cook , Matt Porter , Mel Gorman , Mike Rapoport , Peter Zijlstra , Richard Gong , Sebastian Reichel , Shuah Khan , Steven Rostedt , Sudip Mukherjee , Tony Luck , Vincent Guittot , Will Drewry , linux-fsdevel@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-mm@kvack.org, linux-rdma@vger.kernel.org, target-devel@vger.kernel.org Subject: [PATCH v5 00/16]Fix several bad kernel-doc markups Date: Tue, 1 Dec 2020 13:08:53 +0100 Message-Id: X-Mailer: git-send-email 2.28.0 MIME-Version: 1.0 X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: Kernel-doc has always be limited to a probably bad documented rule: The kernel-doc markups should appear *imediatelly before* the function or data structure that it documents. On other words, if a C file would contain something like this: /** * foo - function foo * @args: foo args */ static inline void bar(int args); /** * bar - function bar * @args: foo args */ static inline void foo(void *args); The output (in ReST format) will be: .. c:function:: void bar (int args) function foo **Parameters** ``int args`` foo args .. c:function:: void foo (void *args) function bar **Parameters** ``void *args`` foo args Which is clearly a wrong result. Before this changeset, not even a warning is produced on such cases. As placing such markups just before the documented data is a common practice, on most cases this is fine. However, as patches touch things, identifiers may be renamed, and people may forget to update the kernel-doc markups to follow such changes. This has been happening for quite a while, as there are lots of files with kernel-doc problems. This series address those issues and add a file at the end that will enforce that the identifier will match the kernel-doc markup, avoiding this problem from keep happening as time goes by. This series is based on current upstream tree. @maintainers: feel free to pick the patches and apply them directly on your trees, as all patches on this series are independent from the other ones. --- v5: - The completion.h patch was replaced by another one which drops an obsolete macro; - Some typos got fixed and review tags got added; - Dropped patches that were already merged at linux-next. v4: - Patches got rebased and got some acks. Mauro Carvalho Chehab (16): HSI: fix a kernel-doc markup IB: fix kernel-doc markups parport: fix a kernel-doc markup rapidio: fix kernel-doc a markup fs: fix kernel-doc markups pstore/zone: fix a kernel-doc markup completion: drop init_completion define firmware: stratix10-svc: fix kernel-doc markups connector: fix a kernel-doc markup lib/crc7: fix a kernel-doc markup memblock: fix kernel-doc markups w1: fix a kernel-doc markup sched: fix kernel-doc markup selftests: kselftest_harness.h: partially fix kernel-doc markups refcount.h: fix a kernel-doc markup scripts: kernel-doc: validate kernel-doc markup with the actual names drivers/hsi/hsi_core.c | 2 +- drivers/infiniband/core/cm.c | 5 +- drivers/infiniband/core/cq.c | 4 +- drivers/infiniband/core/iwpm_util.h | 2 +- drivers/infiniband/core/sa_query.c | 3 +- drivers/infiniband/core/verbs.c | 4 +- drivers/infiniband/sw/rdmavt/ah.c | 2 +- drivers/infiniband/sw/rdmavt/mcast.c | 12 ++-- drivers/infiniband/sw/rdmavt/qp.c | 8 +-- drivers/infiniband/ulp/iser/iscsi_iser.c | 2 +- .../infiniband/ulp/opa_vnic/opa_vnic_encap.h | 2 +- .../ulp/opa_vnic/opa_vnic_vema_iface.c | 2 +- drivers/infiniband/ulp/srpt/ib_srpt.h | 2 +- drivers/parport/share.c | 2 +- drivers/rapidio/rio.c | 2 +- fs/dcache.c | 72 +++++++++---------- fs/inode.c | 4 +- fs/pstore/zone.c | 2 +- fs/seq_file.c | 5 +- fs/super.c | 12 ++-- include/linux/completion.h | 5 +- include/linux/connector.h | 2 +- .../firmware/intel/stratix10-svc-client.h | 10 +-- include/linux/memblock.h | 4 +- include/linux/parport.h | 31 ++++++++ include/linux/refcount.h | 2 +- include/linux/w1.h | 2 +- include/rdma/ib_verbs.h | 11 +++ kernel/sched/core.c | 16 ++--- kernel/sched/fair.c | 2 +- lib/crc7.c | 2 +- scripts/kernel-doc | 62 +++++++++++----- tools/testing/selftests/kselftest_harness.h | 22 +++--- 33 files changed, 197 insertions(+), 123 deletions(-)