Skip to content

Fix several bad kernel-doc markups

Mauro Carvalho Chehab dri-devel linux-doc linux-fsdevel linux-kselftest linux-media linux-mm linux-wireless lkml netdev oe-kbuild-all platform-driver-x86 5 versions – Applied

Status from this message: Thank you, applied to reset/next.

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v6 Latest16 patches 11 repliesApplied
  2. v516 patches 12 repliesSuperseded
  3. v4 posting 2/227 patches 20 repliesApplied 2/27
Earlier versions · 2
VersionPostedPatchesRepliesStatus
v4 posting 1/22 patches1 replySuperseded
v356 patches63 repliesApplied

Changes in v6 from the cover letter

- rebased on the top of next-20210114 and added a few extra fixes

Patches in v6 Applied

#Subject and filesSizeRepliesApplied
1/16parport: fix a kernel-doc markupdrivers/parport/share.c include/linux/parport.h+32 -10 replies
2/16rapidio: fix kernel-doc a markupdrivers/rapidio/rio.c+1 -10 replies
3/16fs: fix kernel-doc markupsfs/dcache.c fs/inode.c fs/seq_file.c +1 more+48 -460 replies
4/16pstore/zone: fix a kernel-doc markupfs/pstore/zone.c+1 -10 replies
5/16firmware: stratix10-svc: fix kernel-doc markupsinclude/linux/firmware/intel/stratix10-svc-client.h+5 -50 replies
6/16connector: fix a kernel-doc markupinclude/linux/connector.h+1 -10 replies
7/16lib/crc7: fix a kernel-doc markuplib/crc7.c+1 -10 replies
8/16memblock: fix kernel-doc markupsinclude/linux/memblock.h+2 -20 replies
9/16w1: fix a kernel-doc markupinclude/linux/w1.h+1 -10 replies
10/16selftests: kselftest_harness.h: partially fix kernel-doc markupstools/testing/selftests/kselftest_harness.h+15 -110 replies
11/16scripts: kernel-doc: validate kernel-doc markup with the actual namesscripts/kernel-doc+46 -162 replies
12/16net: tip: fix a couple kernel-doc markupsnet/tipc/link.c net/tipc/node.c+2 -23 replies
13/16net: cfg80211: fix a kerneldoc markupinclude/net/cfg80211.h+1 -10 replies
14/16reset: core: fix a kernel-doc markupdrivers/reset/core.c+2 -21 reply
15/16drm: drm_crc: fix a kernel-doc markupinclude/drm/drm_crtc.h+1 -12 replies
16/16platform/surface: aggregator: fix a kernel-doc markupdrivers/platform/surface/aggregator/ssh_request_layer.c+1 -12 replies

Reviews trailers per patch

7 of 16 patches have a Reviewed-by or Acked-by.

PatchMike RapoportRichard GongKees CookSimon SerMaximilian LuzJon Maloy
1/16
2/16
3/16
4/16R-b
5/16A-b
6/16
7/16
8/16A-b
9/16
10/16A-b
11/16
12/16A-b
13/16
14/16
15/16A-b
16/16R-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes. Scroll the table sideways for all 6 reviewers.

Read the v6 thread

Cover letter [PATCH v6 00/16] Fix several bad kernel-doc markups

Hi Jon,

This series have three parts:

1) 10 remaining fixup patches from the series I sent back on Dec, 1st:

parport: fix a kernel-doc markup
rapidio: fix kernel-doc a markup
fs: fix kernel-doc markups
pstore/zone: fix a kernel-doc markup
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
selftests: kselftest_harness.h: partially fix kernel-doc markups

2) The patch adding the new check to ensure that the kernel-doc markup will be used for the right declaration;

3) 5 additional patches, produced against next-20210114 with new problems detected after the original series:

net: tip: fix a couple kernel-doc markups
net: cfg80211: fix a kerneldoc markup
reset: core: fix a kernel-doc markup
drm: drm_crc: fix a kernel-doc markup platform/surface: aggregator: fix a kernel-doc markup

It probably makes sense to merge at least the first 11 patches via the doc tree, as they should apply cleanly there, and having the last 5 patches merged via each maintainer's tree.

-

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.

--

v6:
- rebased on the top of next-20210114 and added a few extra fixes

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):
parport: fix a kernel-doc markup
rapidio: fix kernel-doc a markup
fs: fix kernel-doc markups
pstore/zone: fix a kernel-doc markup
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
selftests: kselftest_harness.h: partially fix kernel-doc markups
scripts: kernel-doc: validate kernel-doc markup with the actual names
net: tip: fix a couple kernel-doc markups
net: cfg80211: fix a kerneldoc markup
reset: core: fix a kernel-doc markup
drm: drm_crc: fix a kernel-doc markup
platform/surface: aggregator: fix a kernel-doc markup

 drivers/parport/share.c                       |  2 +-
 .../surface/aggregator/ssh_request_layer.c    |  2 +-
 drivers/rapidio/rio.c                         |  2 +-
 drivers/reset/core.c                          |  4 +-
 fs/dcache.c                                   | 73 ++++++++++---------
 fs/inode.c                                    |  4 +-
 fs/pstore/zone.c                              |  2 +-
 fs/seq_file.c                                 |  5 +-
 fs/super.c                                    | 12 +--
 include/drm/drm_crtc.h                        |  2 +-
 include/linux/connector.h                     |  2 +-
 .../firmware/intel/stratix10-svc-client.h     | 10 +--
 include/linux/memblock.h                      |  4 +-
 include/linux/parport.h                       | 31 ++++++++
 include/linux/w1.h                            |  2 +-
 include/net/cfg80211.h                        |  2 +-
 lib/crc7.c                                    |  2 +-
 net/tipc/link.c                               |  2 +-
 net/tipc/node.c                               |  2 +-
 scripts/kernel-doc                            | 62 ++++++++++++----
 tools/testing/selftests/kselftest_harness.h   | 26 ++++---
 21 files changed, 160 insertions(+), 93 deletions(-)
Signature · 1 line
2.29.2