From 71a44b01a90331ec4ffb9c5d462939e9ca4d2282 Mon Sep 17 00:00:00 2001
From: Simon McVittie <smcv@collabora.com>
Date: Thu, 1 Aug 2019 16:10:31 +0100
Subject: [PATCH] SrtSystemInfo: Document initial public methods

Signed-off-by: Simon McVittie <smcv@collabora.com>
---
 steam-runtime-tools/system-info.c | 56 +++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/steam-runtime-tools/system-info.c b/steam-runtime-tools/system-info.c
index 55e5d9f93..f460febb3 100644
--- a/steam-runtime-tools/system-info.c
+++ b/steam-runtime-tools/system-info.c
@@ -213,6 +213,25 @@ srt_system_info_class_init (SrtSystemInfoClass *cls)
   g_object_class_install_properties (object_class, N_PROPERTIES, properties);
 }
 
+/**
+ * srt_system_info_new:
+ * @expectations: (nullable) (type filename): Path to a directory
+ *  containing details of the state that the system is expected to have
+ *
+ * Return a new #SrtSystemInfo.
+ *
+ * The @expectations directory should contain a subdirectory for each
+ * supported CPU architecture, named for the multiarch tuple as printed
+ * by `gcc -print-multiarch` in the Steam Runtime (in practice this means
+ * %SRT_ABI_I386 or %SRT_ABI_X86_64).
+ *
+ * The per-architecture directories may contain files whose names end with
+ * `.symbols`. Those files are interpreted as describing libraries that
+ * the runtime environment should support, in
+ * [deb-symbols(5)](https://manpages.debian.org/deb-symbols.5) format.
+ *
+ * Returns: (transfer full): A new #SrtSystemInfo. Free with g_object_unref()
+ */
 SrtSystemInfo *
 srt_system_info_new (const char *expectations)
 {
@@ -224,6 +243,32 @@ srt_system_info_new (const char *expectations)
                        NULL);
 }
 
+/**
+ * srt_system_info_can_run:
+ * @self: A #SrtSystemInfo object
+ * @multiarch_tuple: A multiarch tuple defining an ABI, as printed
+ *  by `gcc -print-multiarch` in the Steam Runtime
+ *
+ * Check whether an executable for the given ABI can be run.
+ *
+ * For this check (and all similar checks) to work as intended, the
+ * contents of the `libsteam-runtime-tools-0-helpers:i386` package must
+ * be available in the same directory hierarchy as the
+ * `libsteam-runtime-tools-0` shared library, something like this:
+ *
+ * |[
+ * any directory/
+ *      lib/
+ *          x86_64-linux-gnu/
+ *              libsteam-runtime-tools-0.so.0
+ *      libexec/
+ *          steam-runtime-tools-0/
+ *              i386-linux-gnu-*
+ *              x86_64-linux-gnu-*
+ * ]|
+ *
+ * Returns: %TRUE if executables belonging to @multiarch_tuple can be run
+ */
 gboolean
 srt_system_info_can_run (SrtSystemInfo *self,
                          const char *multiarch_tuple)
@@ -246,6 +291,17 @@ srt_system_info_can_run (SrtSystemInfo *self,
   return (abi->can_run == TRI_YES);
 }
 
+/**
+ * srt_system_info_can_write_to_uinput:
+ * @self: a #SrtSystemInfo object
+ *
+ * Return %TRUE if the current user can write to `/dev/uinput`.
+ * This is required for the Steam client to be able to emulate gamepads,
+ * keyboards, mice and other input devices based on input from the
+ * Steam Controller or a remote streaming client.
+ *
+ * Returns: %TRUE if `/dev/uinput` can be opened for writing
+ */
 gboolean
 srt_system_info_can_write_to_uinput (SrtSystemInfo *self)
 {
-- 
GitLab