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

[Andrea Cervesato]

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.

Signed-off-by: Andrea Cervesato <andrea.cervesato@suse.com>
---
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/20260605-doc_add_missing_headers-v6-0-678aac302a60@suse.com

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/20260604-doc_add_missing_headers-v5-0-2e0adc082d5a@suse.com

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/20260603-doc_add_missing_headers-v4-0-1fe3a372c155@suse.com

Changes in v4:
- fix build errors
- Link to v3: https://lore.kernel.org/r/20260602-doc_add_missing_headers-v3-0-474deff77d2a@suse.com

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/20260602-doc_add_missing_headers-v2-0-9ccd988c093d@suse.com

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/20260601-doc_add_missing_headers-v1-0-6f1ee31945df@suse.com

---
Andrea Cervesato (2):
      doc: Add missing API references to api_c_tests.rst
      doc: Complete struct tst_test table and shell API docs

 doc/developers/api_c_tests.rst     |  71 +++++++++---
 doc/developers/api_shell_tests.rst | 183 +++++++++++++++++++++++++++++
 doc/developers/writing_tests.rst   |  28 ++++-
 include/tse_uinput.h               |  30 ++---
 include/tst_clone.h                |  24 ++--
 include/tst_device.h               | 166 ++++++++++++++++----------
 include/tst_fuzzy_sync.h           | 232 ++++++++++++++++++-------------------
 include/tst_hugepage.h             |  35 ++++--
 include/tst_kconfig.h              |  78 ++++++-------
 include/tst_taint.h                |  32 ++---
 10 files changed, 586 insertions(+), 293 deletions(-)
---
base-commit: 1efb4bb8eb4a8582284a90a70ca2adc22c4e47b0
change-id: 20260601-doc_add_missing_headers-ca51d98d32ac

Best regards,
-- 
Andrea Cervesato <andrea.cervesato@suse.com>