[igt-dev] [PATCH i-g-t 02/36] lib: Document igt_opt_handler_t semantics

[Petri Latvala]

Best practices for the help string formatting, along with explicit
symbols for the possible return values for the callback.

Also documented: Do not call the _parse_opts functions yourself, use
igt_main_args or igt_simple_main_args.

Signed-off-by: Petri Latvala <petri.latvala at intel.com>
---
 lib/igt_core.c | 31 ++++++++++++++++++++++++++++---
 lib/igt_core.h |  2 ++
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/lib/igt_core.c b/lib/igt_core.c
index 9ef18eb1..9c86d664 100644
--- a/lib/igt_core.c
+++ b/lib/igt_core.c
@@ -857,8 +857,18 @@ out:
  * additional knobs to tune when run manually like the number of rounds execute
  * or the size of the allocated buffer objects.
  *
- * Tests without special needs should just use igt_subtest_init() or use
- * #igt_main directly instead of their own main() function.
+ * Tests should use #igt_main_args instead of their own main()
+ * function and calling this function.
+ *
+ * The @help_str parameter is printed directly after the help text of
+ * standard arguments. The formatting of the string should be:
+ * - One line per option
+ * - Two spaces, option flag, tab character, help text, newline character
+ *
+ * Example: "  -s\tBuffer size\n"
+ *
+ * The opt handler function must return #IGT_OPT_HANDLER_SUCCESS on
+ * successful handling, #IGT_OPT_HANDLER_ERROR on errors.
  *
  * Returns: Forwards any option parsing errors from getopt_long.
  */
@@ -891,7 +901,22 @@ enum igt_log_level igt_log_level = IGT_LOG_INFO;
  * @handler_data: user data given to @extra_opt_handler when invoked
  *
  * This initializes a simple test without any support for subtests and allows
- * an arbitrary set of additional options.
+ * an arbitrary set of additional options. This is useful for tests which have
+ * additional knobs to tune when run manually like the number of rounds execute
+ * or the size of the allocated buffer objects.
+ *
+ * Tests should use #igt_simple_main_args instead of their own main()
+ * function and calling this function.
+ *
+ * The @help_str parameter is printed directly after the help text of
+ * standard arguments. The formatting of the string should be:
+ * - One line per option
+ * - Two spaces, option flag, tab character, help text, newline character
+ *
+ * Example: "  -s\tBuffer size\n"
+ *
+ * The opt handler function must return #IGT_OPT_HANDLER_SUCCESS on
+ * successful handling, #IGT_OPT_HANDLER_ERROR on errors.
  */
 void igt_simple_init_parse_opts(int *argc, char **argv,
 				const char *extra_short_opts,
diff --git a/lib/igt_core.h b/lib/igt_core.h
index cd89921e..88a95ec2 100644
--- a/lib/igt_core.h
+++ b/lib/igt_core.h
@@ -145,6 +145,8 @@ void __igt_fixture_end(void) __attribute__((noreturn));
 /* subtest infrastructure */
 jmp_buf igt_subtest_jmpbuf;
 typedef int (*igt_opt_handler_t)(int opt, int opt_index, void *data);
+#define IGT_OPT_HANDLER_SUCCESS 0
+#define IGT_OPT_HANDLER_ERROR -2
 #ifndef __GTK_DOC_IGNORE__ /* gtkdoc wants to document this forward decl */
 struct option;
 #endif
-- 
2.19.1