Skip to contentSkip to conversation

doc: Add generated API docs

PATCH Superseded Cyril Hrubis 1 participant 4 messages Apr 2, 2024 – Apr 3, 2024

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

v2 cover doc: Add generated API docs

This applies over the new doc patchset from Andrea and converts documentation in headers into a linuxdoc format.

This is a v2 with spelling fixes hopefully all the easily caught mistakes are fixed now.

If you have a bit of time please read the changes through and report any problems.

Cyril Hrubis (2):
doc: Add more to spelling_wordlist
include: doc: Convert comments into linuxdoc

 doc_new/developers/api_c_tests.rst |  26 ++
 doc_new/spelling_wordlist          |  40 +++
 include/tst_buffers.h              |  86 +++--
 include/tst_capability.h           |  80 ++++-
 include/tst_checkpoint.h           |  64 +++-
 include/tst_compiler.h             |  20 ++
 include/tst_hugepage.h             |   2 +
 include/tst_parse.h                |  65 ++++
 include/tst_res_flags.h            |  72 +++-
 include/tst_test.h                 | 509 +++++++++++++++++++++--------
 10 files changed, 762 insertions(+), 202 deletions(-)
 create mode 100644 include/tst_compiler.h
 create mode 100644 include/tst_parse.h
Signature · 5 lines
2.43.2


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
#1 lore raw

PATCH v2 1/2 doc: Add more to spelling_wordlist

+ Computer jargon
+ LTP variable and constant names

Not everything has been added. E.g. I've avoided adding filesystems used in variable names because it's supposed to be two words in text.

---
 doc_new/spelling_wordlist | 40 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)
doc_new/spelling_wordlist +40 -0
index 0c016e615..de1e3721e 100644
@@ -118,3 +118,43 @@ vCPUs
 vendoring
 vger
 wallclock
+pid
+TBROK
+mkfs
+hugepages
+hugetlbfs
+printf
+scanf
+argv
+argc
+pthread
+futex
+hdr
+brk
+iovec
+iov
+strdup
+aprintf
+alloc
+hexd
+tcases
+strsig
+strstatus
+strerrno
+libcap
+capset
+capget
+musl
+setrlimit
+rlim
+optstr
+tmpfs
+nodev
+sys
+proc
+arg
+ver
+bitwise
+dereferenced
+allocator
+ptr
Signature · 5 lines
2.43.2


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
#2 lore raw

PATCH v2 2/2 include: doc: Convert comments into linuxdoc

In reply to Cyril Hrubis

From: Cyril Hrubis <[email protected]>

---
 doc_new/developers/api_c_tests.rst |  26 ++
 include/tst_buffers.h              |  86 +++--
 include/tst_capability.h           |  80 ++++-
 include/tst_checkpoint.h           |  64 +++-
 include/tst_compiler.h             |  20 ++
 include/tst_hugepage.h             |   2 +
 include/tst_parse.h                |  65 ++++
 include/tst_res_flags.h            |  72 +++-
 include/tst_test.h                 | 509 +++++++++++++++++++++--------
 9 files changed, 722 insertions(+), 202 deletions(-)
 create mode 100644 include/tst_compiler.h
 create mode 100644 include/tst_parse.h
doc_new/developers/api_c_tests.rst +26 -0
index adee17f16..2c0c8419d 100644
@@ -5,3 +5,29 @@
 
 Developing using C API
 ======================
+
+Core LTP API
+------------
+
+.. kernel-doc:: ../../include/tst_res_flags.h
+.. kernel-doc:: ../../include/tst_test.h
+
+Option parsing
+--------------
+
+.. kernel-doc:: ../../include/tst_parse.h
+
+Guarded buffers
+---------------
+
+.. kernel-doc:: ../../include/tst_buffers.h
+
+Checkpoints
+-----------
+
+.. kernel-doc:: ../../include/tst_checkpoint.h
+
+Capabilities
+------------
+
+.. kernel-doc:: ../../include/tst_capability.h
include/tst_buffers.h +56 -30

125 lines not on this page · raw message

include/tst_capability.h +66 -14

134 lines not on this page · raw message

include/tst_checkpoint.h +63 -1

87 lines not on this page · raw message

include/tst_compiler.h new file +20 -0
new file mode 100644
index 000000000..ec88213df
@@ -0,0 +1,20 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
+/**
+ * @file tst_compiler.h
+ * @brief Macros to support dumb compilers.
+ *
+ * The doxygen parser (and possibly other C tooling) does not understand
+ * __attributes__ so we have to hide them with macros.
+ */
+
+#ifndef TST_COMPILER_H__
+#define TST_COMPILER_H__
+
+#ifdef __GNUC__
+# define TST_ATTRIBUTE(...) __attribute__((__VA_ARGS__))
+#else
+# define TST_ATTRIBUTE(...)
+#endif
+
+#endif	/* TST_COMPILER_H__ */
include/tst_hugepage.h +2 -0
index 46327c79a..6b865b2f2 100644
@@ -24,6 +24,8 @@ enum tst_hp_policy {
 	TST_NEEDS,
 };
 
+#define TST_NO_HUGEPAGES ((unsigned long)-1)
+
 struct tst_hugepage {
 	const unsigned long number;
 	enum  tst_hp_policy policy;
include/tst_parse.h new file +65 -0

65 lines not on this page · raw message

include/tst_res_flags.h +57 -15

81 lines not on this page · raw message

include/tst_test.h +367 -142

690 lines not on this page · raw message

Signature · 5 lines
2.43.2


-- 
Mailing list info: https://lists.linux.it/listinfo/ltp
#3 lore raw

Re: [LTP] [PATCH v2 2/2] include: doc: Convert comments into linuxdoc

Hi!

Quoted 16 lines
include/tst_compiler.h new file +10 -0
new file mode 100644
index 000000000..ec88213df
@@ -0,0 +1,20 @@
+/* SPDX-License-Identifier: GPL-2.0-or-later */
+
+/**
+ * @file tst_compiler.h
+ * @brief Macros to support dumb compilers.
+ *
+ * The doxygen parser (and possibly other C tooling) does not understand
+ * __attributes__ so we have to hide them with macros.
+ */
+

include/tst_compiler.h line 20

Quoted 10 lines
include/tst_compiler.h new file +10 -0
+#ifndef TST_COMPILER_H__
+#define TST_COMPILER_H__
+
+#ifdef __GNUC__
+# define TST_ATTRIBUTE(...) __attribute__((__VA_ARGS__))
+#else
+# define TST_ATTRIBUTE(...)
+#endif
+
+#endif	/* TST_COMPILER_H__ */

And I just realized that this is a leftover from the doxygen experiment, so it should be dropped from the patchset. I will send a v3.

Signature · 5 lines
Cyril Hrubis
[email protected]

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