Fix several bad kernel-doc markups
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
- v6 Latest16 patches 11 repliesApplied
- v516 patches 12 repliesSuperseded
- v4 posting 2/227 patches 20 repliesApplied 2/27
Earlier versions · 2
| Version | Posted | Patches | Replies | Status |
|---|---|---|---|---|
| v4 posting 1/2 | 2 patches | 1 reply | Superseded | |
| v3 | 56 patches | 63 replies | Applied |
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 files | Size | Replies | Applied |
|---|---|---|---|---|
| 1/16 | parport: fix a kernel-doc markupdrivers/ include/ | +32 | 0 replies | |
| 2/16 | rapidio: fix kernel-doc a markupdrivers/ | +1 | 0 replies | |
| 3/16 | fs: fix kernel-doc markupsfs/ fs/ fs/ +1 more | +48 | 0 replies | |
| 4/16 | pstore/zone: fix a kernel-doc markupfs/ | +1 | 0 replies | |
| 5/16 | firmware: stratix10-svc: fix kernel-doc markupsinclude/ | +5 | 0 replies | |
| 6/16 | connector: fix a kernel-doc markupinclude/ | +1 | 0 replies | |
| 7/16 | lib/crc7: fix a kernel-doc markuplib/ | +1 | 0 replies | |
| 8/16 | memblock: fix kernel-doc markupsinclude/ | +2 | 0 replies | |
| 9/16 | w1: fix a kernel-doc markupinclude/ | +1 | 0 replies | |
| 10/16 | selftests: kselftest_harness.h: partially fix kernel-doc markupstools/ | +15 | 0 replies | |
| 11/16 | scripts: kernel-doc: validate kernel-doc markup with the actual namesscripts/ | +46 | 2 replies | |
| 12/16 | net: tip: fix a couple kernel-doc markupsnet/ net/ | +2 | 3 replies | |
| 13/16 | net: cfg80211: fix a kerneldoc markupinclude/ | +1 | 0 replies | |
| 14/16 | reset: core: fix a kernel-doc markupdrivers/ | +2 | 1 reply | |
| 15/16 | drm: drm_crc: fix a kernel-doc markupinclude/ | +1 | 2 replies | |
| 16/16 | platform/surface: aggregator: fix a kernel-doc markupdrivers/ | +1 | 2 replies |
Reviews trailers per patch
7 of 16 patches have a Reviewed-by or Acked-by.
| Patch | Mike Rapoport | Richard Gong | Kees Cook | Simon Ser | Maximilian Luz | Jon Maloy |
|---|---|---|---|---|---|---|
| 1/16 | ||||||
| 2/16 | ||||||
| 3/16 | ||||||
| 4/16 | R-b | |||||
| 5/16 | A-b | |||||
| 6/16 | ||||||
| 7/16 | ||||||
| 8/16 | A-b | |||||
| 9/16 | ||||||
| 10/16 | A-b | |||||
| 11/16 | ||||||
| 12/16 | A-b | |||||
| 13/16 | ||||||
| 14/16 | ||||||
| 15/16 | A-b | |||||
| 16/16 | R-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.
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