Docs: add informal comments to common-internal.h

Signed-off-by: Philippe Proulx <eeppeliteloop@gmail.com>
Signed-off-by: Jérémie Galarneau <jeremie.galarneau@efficios.com>

diff --git a/include/babeltrace/common-internal.h b/include/babeltrace/common-internal.h
index b843e57ec1aa738bec9d4804a19860fdfcd6c39d..eb055f5e5eeffc0db92eb5e8d3b7641cad3bff9d 100644 (file)
--- a/include/babeltrace/common-internal.h
+++ b/include/babeltrace/common-internal.h
@@ -33,18 +33,40 @@ struct bt_common_lttng_live_url_parts {
        int port;
 };
 
+/*
+ * Checks if the current process has setuid or setgid access rights.
+ * Returns `true` if so.
+ */
 BT_HIDDEN
 bool bt_common_is_setuid_setgid(void);
 
+/*
+ * Returns the system-wide plugin path, e.g.
+ * `/usr/lib/babeltrace/plugins`. Do not free the return value.
+ */
 BT_HIDDEN
 const char *bt_common_get_system_plugin_path(void);
 
+/*
+ * Returns the user plugin path, e.g.
+ * `/home/user/.local/lib/babeltrace/plugins`. You need to free the
+ * return value.
+ */
 BT_HIDDEN
 char *bt_common_get_home_plugin_path(void);
 
+/*
+ * Appends the list of directories in `paths` to the array `dirs`.
+ * `paths` is a list of directories separated by `:`. Returns 0 on
+ * success.
+ */
 BT_HIDDEN
 int bt_common_append_plugin_path_dirs(const char *paths, GPtrArray *dirs);
 
+/*
+ * Returns `true` if terminal color codes are supported for this
+ * process.
+ */
 BT_HIDDEN
 bool bt_common_colors_supported(void);
 
@@ -102,31 +124,78 @@ const char *bt_common_color_bg_cyan(void);
 BT_HIDDEN
 const char *bt_common_color_bg_light_gray(void);
 
+/*
+ * Returns the substring from `input` to the first character found
+ * in the list of characters `end_chars`, unescaping any character
+ * found in `escapable_chars`, and sets `*end_pos` to the position of
+ * the end (from `input`). The caller owns the returned GString.
+ */
 BT_HIDDEN
 GString *bt_common_string_until(const char *input, const char *escapable_chars,
                     const char *end_chars, size_t *end_pos);
 
+/*
+ * Returns the quoted version of `input` for a shell. If
+ * `with_single_quotes` is `true`, prepends and appends the `'` prefix
+ * and suffix to the returned string; otherwise the caller should
+ * prepend and append them manually, although they are not always
+ * required. The caller owns the returned GString.
+ */
 BT_HIDDEN
 GString *bt_common_shell_quote(const char *input, bool with_single_quotes);
 
+/*
+ * Returns `true` if `input` is a string made only of printable
+ * characters.
+ */
 BT_HIDDEN
 bool bt_common_string_is_printable(const char *input);
 
+/*
+ * Destroys the parts of an LTTng live URL as returned by
+ * bt_common_parse_lttng_live_url().
+ */
 BT_HIDDEN
 void bt_common_destroy_lttng_live_url_parts(
                struct bt_common_lttng_live_url_parts *parts);
 
+/*
+ * Parses the LTTng live URL `url` and returns its different parts.
+ * If there's an error, writes the error message into `*error_buf`
+ * up to `error_buf_size` bytes. You must destroy the returned value
+ * with bt_common_destroy_lttng_live_url_parts().
+ */
 BT_HIDDEN
 struct bt_common_lttng_live_url_parts bt_common_parse_lttng_live_url(
                const char *url, char *error_buf, size_t error_buf_size);
 
+/*
+ * Normalizes (in place) a star globbing pattern to be used with
+ * bt_common_star_glob_match(). This function always succeeds.
+ */
 BT_HIDDEN
 void bt_common_normalize_star_glob_pattern(char *pattern);
 
+/*
+ * Returns `true` if `candidate` (of size `candidate_len`) matches
+ * the star globbing pattern `pattern` (of size `pattern_len`).
+ */
 BT_HIDDEN
 bool bt_common_star_glob_match(const char *pattern, size_t pattern_len,
                 const char *candidate, size_t candidate_len);
 
+/*
+ * Normalizes the path `path`:
+ *
+ * * If it's a relative path, converts it to an absolute path using
+ *   `wd` as the working directory (or the current working directory
+ *   if `wd` is NULL).
+ * * Removes consecutive and trailing slashes.
+ * * Resolves `..` and `.` in the path (both in `path` and in `wd`).
+ * * Does NOT resolve symbolic links.
+ *
+ * The caller owns the returned GString.
+ */
 BT_HIDDEN
 GString *bt_common_normalize_path(const char *path, const char *wd);