[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.

Signed-off-by: Andrea Cervesato <andrea.cervesato-IBi9RG/[email protected]>
---
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/20260609-doc_add_missing_headers-v7-0-779c18caddef-IBi9RG/[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/20260605-doc_add_missing_headers-v6-0-678aac302a60-IBi9RG/[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/20260604-doc_add_missing_headers-v5-0-2e0adc082d5a-IBi9RG/[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/20260603-doc_add_missing_headers-v4-0-1fe3a372c155-IBi9RG/[email protected]

Changes in v4:
- fix build errors
- Link to v3: https://lore.kernel.org/r/20260602-doc_add_missing_headers-v3-0-474deff77d2a-IBi9RG/[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/20260602-doc_add_missing_headers-v2-0-9ccd988c093d-IBi9RG/[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/20260601-doc_add_missing_headers-v1-0-6f1ee31945df-IBi9RG/[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,
-- 
Andrea Cervesato <andrea.cervesato-IBi9RG/[email protected]>


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