From patchwork Mon Nov 16 10:17:56 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: 11907945 Return-Path: Received: from mail.kernel.org (pdx-korg-mail-1.web.codeaurora.org [172.30.200.123]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 0B5C71391 for ; Mon, 16 Nov 2020 10:18:37 +0000 (UTC) Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.kernel.org (Postfix) with ESMTP id 85B852227F for ; Mon, 16 Nov 2020 10:18:36 +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="nOYrZpl4" DMARC-Filter: OpenDMARC Filter v1.3.2 mail.kernel.org 85B852227F 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 73ED56B0068; Mon, 16 Nov 2020 05:18:33 -0500 (EST) Delivered-To: linux-mm-outgoing@kvack.org Received: by kanga.kvack.org (Postfix, from userid 40) id 6CB166B006C; Mon, 16 Nov 2020 05:18:33 -0500 (EST) X-Original-To: int-list-linux-mm@kvack.org X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 50E906B006E; Mon, 16 Nov 2020 05:18:33 -0500 (EST) X-Original-To: linux-mm@kvack.org X-Delivered-To: linux-mm@kvack.org Received: from forelay.hostedemail.com (smtprelay0044.hostedemail.com [216.40.44.44]) by kanga.kvack.org (Postfix) with ESMTP id 19B726B0068 for ; Mon, 16 Nov 2020 05:18:33 -0500 (EST) Received: from smtpin11.hostedemail.com (10.5.19.251.rfc1918.com [10.5.19.251]) by forelay03.hostedemail.com (Postfix) with ESMTP id A1D0C8249980 for ; Mon, 16 Nov 2020 10:18:32 +0000 (UTC) X-FDA: 77489882064.11.spy82_580286027328 Received: from filter.hostedemail.com (10.5.16.251.rfc1918.com [10.5.16.251]) by smtpin11.hostedemail.com (Postfix) with ESMTP id 82F01180F8B81 for ; Mon, 16 Nov 2020 10:18:32 +0000 (UTC) X-Spam-Summary: 1,0,0,fca7e427828c9e12,d41d8cd98f00b204,mchehab@kernel.org,,RULES_HIT:1:2:41:69:355:379:541:857:966:973:982:988:989:1260:1311:1314:1345:1437:1515:1605:1730:1747:1777:1792:1801:1981:2194:2196:2198:2199:2200:2201:2393:2553:2559:2562:2693:2895:3138:3139:3140:3141:3142:3865:3866:3867:3868:3870:3871:3872:3874:4050:4385:4605:5007:6261:6653:6742:6743:7875:7904:7974:9010:10004:11026:11658:11914:12043:12297:12438:12517:12519:12679:12895:13161:13229:13894:14096:14394:21063:21080:21222:21325:21451:21627:21773:21809:21939:30003:30030:30054:30055:30056:30060:30069:30070:30090,0,RBL:198.145.29.99:@kernel.org:.lbl8.mailshell.net-62.2.0.100 64.100.201.201;04yrcckbc678d4e9jkck31ipa8d5wopfcdwcrd9o7mj99f1yhhx58uhet3a6pq9.xrneeiwc6zba94x5bqaewa5entgtc5q8k1o83xx9tib767ijbwwt6fgkjceqy6g.g-lbl8.mailshell.net-223.238.255.100,CacheIP:none,Bayesian:0.5,0.5,0.5,Netcheck:none,DomainCache:0,MSF:not bulk,SPF:fp,MSBL:0,DNSBL:neutral,Custom_rules:0:0:0,LFtime:70,LUA_SUMMARY:none X-HE-Tag: spy82_580286027328 X-Filterd-Recvd-Size: 10808 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by imf25.hostedemail.com (Postfix) with ESMTP for ; Mon, 16 Nov 2020 10:18:31 +0000 (UTC) Received: from mail.kernel.org (ip5f5ad5de.dynamic.kabel-deutschland.de [95.90.213.222]) (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 6C48B2467D; Mon, 16 Nov 2020 10:18:29 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1605521909; bh=hrYDFejIWKc2Sc1kJcaDxBLFYaPls+fhDdb9MsI3AZg=; h=From:To:Cc:Subject:Date:From; b=nOYrZpl4mWNo4VChMm50rhlZZFPHrNl2Md99UAjXUoT1Rv4ai6qEtKNY48QQHHDZ9 HHi0C1trk4izVD71hsF3fVqJ+98gWWf5nNLgENrcQfgxQXQZ2k1Gs3wz9z2aw/LySR l+js1iuF3inRwlmH2DVzaLCAfu7AYgHEXvSB+IiI= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kebab-00FwDo-Pf; Mon, 16 Nov 2020 11:18:25 +0100 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org, Jonathan Corbet , "David S. Miller" , "Theodore Ts'o" , Alexander Viro , Alexandre Bounine , Andrew Lunn , Andrew Morton , Andy Lutomirski , Anna Schumaker , Anton Vorontsov , Ben Segall , Colin Cross , Daniel Bristot de Oliveira , Daniel Vetter , David Airlie , Dietmar Eggemann , Evgeniy Polyakov , Heiner Kallweit , Ingo Molnar , Jakub Kicinski , Jan Kara , Juri Lelli , Kees Cook , Maarten Lankhorst , Matt Porter , Maxime Ripard , Mel Gorman , Mike Rapoport , Peter Zijlstra , Richard Gong , Russell King , Sebastian Reichel , Shuah Khan , Steven Rostedt , Sudip Mukherjee , Thomas Gleixner , Thomas Zimmermann , Tony Luck , Trond Myklebust , Vincent Guittot , Will Drewry , dri-devel@lists.freedesktop.org, intel-gfx@lists.freedesktop.org, linux-ext4@vger.kernel.org, linux-fbdev@vger.kernel.org, linux-fsdevel@vger.kernel.org, linux-kselftest@vger.kernel.org, linux-mm@kvack.org, linux-nfs@vger.kernel.org, linux-rdma@vger.kernel.org, linux-s390@vger.kernel.org, netdev@vger.kernel.org, target-devel@vger.kernel.org Subject: [PATCH v4 00/27]Fix several bad kernel-doc markups Date: Mon, 16 Nov 2020 11:17:56 +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. --- v4: - Patches got rebased and got some acks. Mauro Carvalho Chehab (27): net: phy: fix kernel-doc markups net: datagram: fix some kernel-doc markups net: core: fix some kernel-doc markups s390: fix kernel-doc markups drm: fix some kernel-doc markups HSI: fix a kernel-doc markup IB: fix kernel-doc markups parport: fix a kernel-doc markup rapidio: fix kernel-doc a markup video: fix some kernel-doc markups fs: fix kernel-doc markups jbd2: fix kernel-doc markups pstore/zone: fix a kernel-doc markup completion: fix kernel-doc markups firmware: stratix10-svc: fix kernel-doc markups connector: fix a kernel-doc markup lib/crc7: fix a kernel-doc markup hrtimer: fix kernel-doc markups genirq: fix kernel-doc markups list: fix a typo at the kernel-doc markup memblock: fix kernel-doc markups w1: fix a kernel-doc markup resource: fix kernel-doc markups shed: fix kernel-doc markup mm: fix kernel-doc markups selftests: kselftest_harness.h: partially fix kernel-doc markups scripts: kernel-doc: validate kernel-doc markup with the actual names arch/s390/include/asm/ccwdev.h | 2 +- arch/s390/include/asm/cio.h | 2 +- drivers/gpu/drm/drm_atomic_state_helper.c | 2 +- drivers/gpu/drm/drm_connector.c | 3 +- drivers/gpu/drm/drm_dp_helper.c | 2 +- drivers/gpu/drm/drm_framebuffer.c | 2 +- drivers/gpu/drm/drm_gem.c | 4 +- drivers/gpu/drm/drm_gem_vram_helper.c | 2 +- drivers/gpu/drm/drm_mode_object.c | 2 +- drivers/gpu/drm/drm_modes.c | 4 +- drivers/gpu/drm/drm_scdc_helper.c | 2 +- drivers/gpu/drm/i915/display/intel_dpll_mgr.c | 2 +- drivers/gpu/drm/i915/i915_gem_evict.c | 2 +- drivers/gpu/drm/i915/i915_perf.c | 8 ++- drivers/gpu/drm/scheduler/sched_main.c | 2 +- drivers/gpu/drm/v3d/v3d_sched.c | 2 +- drivers/gpu/drm/vc4/vc4_bo.c | 2 +- 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/net/phy/mdio_bus.c | 2 +- drivers/net/phy/phy-c45.c | 2 +- drivers/net/phy/phy.c | 2 +- drivers/net/phy/phy_device.c | 2 +- drivers/net/phy/phylink.c | 2 +- drivers/parport/share.c | 2 +- drivers/rapidio/rio.c | 2 +- drivers/video/fbdev/core/fbcmap.c | 2 +- drivers/video/hdmi.c | 3 +- fs/dcache.c | 72 +++++++++---------- fs/inode.c | 4 +- fs/jbd2/journal.c | 34 ++++----- fs/jbd2/transaction.c | 31 ++++---- fs/pstore/zone.c | 2 +- fs/seq_file.c | 5 +- fs/super.c | 12 ++-- include/drm/drm_atomic_helper.h | 4 +- include/drm/drm_connector.h | 2 +- include/drm/drm_device.h | 2 +- include/drm/drm_dsc.h | 3 +- include/drm/drm_gem_vram_helper.h | 8 +-- include/linux/completion.h | 10 ++- include/linux/connector.h | 2 +- .../firmware/intel/stratix10-svc-client.h | 10 +-- include/linux/hrtimer.h | 6 +- include/linux/jbd2.h | 2 +- include/linux/list.h | 2 +- include/linux/memblock.h | 4 +- include/linux/netdevice.h | 11 ++- include/linux/parport.h | 31 ++++++++ include/linux/w1.h | 2 +- include/rdma/ib_verbs.h | 11 +++ kernel/irq/chip.c | 2 +- kernel/irq/generic-chip.c | 2 +- kernel/resource.c | 24 ++++--- kernel/sched/core.c | 16 ++--- kernel/sched/fair.c | 2 +- kernel/time/hrtimer.c | 2 +- lib/crc7.c | 2 +- mm/gup.c | 24 ++++--- mm/page_alloc.c | 16 ++--- mm/truncate.c | 10 ++- net/core/datagram.c | 2 +- net/core/dev.c | 4 +- net/core/skbuff.c | 2 +- net/ethernet/eth.c | 6 +- net/sunrpc/rpc_pipe.c | 3 +- scripts/kernel-doc | 62 +++++++++++----- tools/testing/selftests/kselftest_harness.h | 22 +++--- 79 files changed, 350 insertions(+), 235 deletions(-)