Skip to content

doc: Add missing headers and complete API docs

Andrea Cervesato ltp 8 versions – In review

Get series with b4
b4 am [email protected] change-id 20260601-doc_add_missing_headers-ca51d98d32ac

Versions newest first

  1. v8 Latest2 patches 4 repliesIn review
  2. v72 patches 5 repliesSuperseded
  3. v63 patches 3 repliesSuperseded
Earlier versions · 5
VersionPostedPatchesRepliesStatus
v53 patches2 repliesSuperseded
v43 patches2 repliesSuperseded
v33 patches2 repliesSuperseded
v23 patches1 replySuperseded
v13 patches7 repliesSuperseded

Changes in v8 from the cover letter

- PATCH 1: add usage pattern description linking tst_dev_sync() and tst_dev_bytes_written() in tst_device.h
- PATCH 1: remove duplicate inline comments from tst_fzsync_pair struct
fields (already documented in the top-level kernel-doc block)
- PATCH 1: remove stray double '::' in tst_fzsync_pair_update() comment
- PATCH 2: remove Shell API variables
- Link to v7: https://lore.kernel.org/r/[email protected]

Patches in v8 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/2doc: Add missing API references to api_c_tests.rstdoc/developers/api_c_tests.rst include/tse_uinput.h include/tst_clone.h +5 more+361 -3262 replies
2/2doc: complete struct tst_test documentationdoc/developers/writing_tests.rst+26 -21 reply

Reviews trailers per patch

All 2 patches have a Reviewed-by or Acked-by.

PatchPetr VorelCyril Hrubis
1/2R-b R-b
2/2R-b

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v8 thread

Cover letter [LTP] [PATCH v8 0/2] doc: Add missing headers and complete API docs

Add kernel-doc directives for 10 headers that were missing from the C API documentation page and convert plain and Doxygen-style comments to kernel-doc format so the documentation builder can extract them.

Complete the struct tst_test comparison table in writing_tests.rst and add a shell API variables reference to api_shell_tests.rst.

---
Changes in v8:
- PATCH 1: add usage pattern description linking tst_dev_sync() and tst_dev_bytes_written() in tst_device.h
- PATCH 1: remove duplicate inline comments from tst_fzsync_pair struct
fields (already documented in the top-level kernel-doc block)
- PATCH 1: remove stray double '::' in tst_fzsync_pair_update() comment
- PATCH 2: remove Shell API variables
- Link to v7: https://lore.kernel.org/r/[email protected]

Changes in v7:
- Rewrite cover letter subject and body
- Drop the api_safe_macros.rst patch from the series
- Link to v6: https://lore.kernel.org/r/[email protected]

Changes in v6:
- PATCH 3: replace the U+2014 em-dash next to SAFE_CLOSE in
api_safe_macros.rst with an ASCII '--' so doc/ stays ASCII-only
- Link to v5: https://lore.kernel.org/r/[email protected]

Changes in v5:
- PATCH 1: drop the stray empty "Verdict:" line accidentally left in
the commit message body
- PATCH 1: remove the leftover "@sa tst_fzsync_pair" Doxygen directive
from the file-level overview comment in tst_fuzzy_sync.h
- PATCH 2: extend the shell API variables reference with the remaining
public inputs (TST_DISABLE_APPARMOR, TST_DISABLE_SELINUX,
TST_SKIP_LSM_WARNINGS, TST_NO_DEFAULT_RUN, TST_TMPDIR_RHOST)
- Link to v4: https://lore.kernel.org/r/[email protected]

Changes in v4:
- fix build errors
- Link to v3: https://lore.kernel.org/r/[email protected]

Changes in v3:
- PATCH 3: add the missing blank line between tst_mount_has_opt() and
the tst_is_mounted() kernel-doc block in tst_device.h
- PATCH 3: restore the "Requires <string.h>" note (for strlen()) in the TST_KCONFIG_INIT() kernel-doc comment in tst_kconfig.h
- Link to v2: https://lore.kernel.org/r/[email protected]

Changes in v2:
- PATCH 1: drop the incorrect claim about fixing the tse_numa.h
kernel-doc reference (it was already correct) and correct the header
count from 12 to 10 (tse_numa.h and tse_swap.h were already present)
- PATCH 1: remove leftover Doxygen directives (@param, @return,
@relates, @sa) in tst_fuzzy_sync.h that the new kernel-doc comments
superseded
- PATCH 2: drop the already-applied field-rename claims (.runtime,
.hugepages, dev_* moves) from the commit message and correct the
added-field count from 10 to 8
- PATCH 3: fix the copyright year (2025 -> 2026), remove the duplicate
SAFE_MMAP entry from the core macros section, and correct the macro
count from 217 to 216
- Link to v1: https://lore.kernel.org/r/[email protected]

---
Andrea Cervesato (2):
doc: Add missing API references to api_c_tests.rst
doc: complete struct tst_test documentation

 doc/developers/api_c_tests.rst   |  71 +++++++++---
 doc/developers/writing_tests.rst |  28 ++++-
 include/tse_uinput.h             |  30 ++---
 include/tst_clone.h              |  24 ++--
 include/tst_device.h             | 174 ++++++++++++++++++----------
 include/tst_fuzzy_sync.h         | 243 ++++++++++++++-------------------------
 include/tst_hugepage.h           |  35 ++++--
 include/tst_kconfig.h            |  78 ++++++-------
 include/tst_taint.h              |  32 ++----
 9 files changed, 387 insertions(+), 328 deletions(-)

---
base-commit: 6e9798bd429f7f341db078388ddb7087b81fb67b
change-id: 20260601-doc_add_missing_headers-ca51d98d32ac

Best regards,

Signature · 5 lines
Andrea Cervesato <[email protected]>


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp