[ghex/expand-search-options: 14/16] gtkhex: gtk-doc-ify expanded HexDocument API.

[Logan Rathbone <larathbone src gnome org>]

commit d650bcac4b13cf0257c1334e80b54887dede1649
Author: Logan Rathbone <poprocks gmail com>
Date:   Tue Apr 19 22:01:53 2022 -0400

    gtkhex: gtk-doc-ify expanded HexDocument API.

 src/hex-document.c | 75 ++++++++++++++++++++++++++++++++++++++++++++++++++++--
 src/hex-document.h | 17 +++++++++++--
 2 files changed, 88 insertions(+), 4 deletions(-)
---
diff --git a/src/hex-document.c b/src/hex-document.c
index 4fd189a..54cd2f6 100644
--- a/src/hex-document.c
+++ b/src/hex-document.c
@@ -1095,6 +1095,22 @@ hex_document_export_html (HexDocument *doc,
        return TRUE;
 }
 
+/**
+ * hex_document_compare_data_full:
+ * @find_data: a #HexDocumentFindData structure
+ * @pos: offset position of the #HexDocument data to compare with the
+ *   string contained in the `find_data` structure
+ *
+ * Full version of [method@Hex.Document.compare_data] to allow data
+ * comparisons broader than byte-for-byte matches only. However, it is
+ * less convenient than the above since it requires the caller to allocate
+ * and free a #HexDocumentFindData structure.
+ *
+ * Returns: 0 if the comparison is an exact match; otherwise, a non-zero
+ *   value is returned.
+ *
+ * Since: 4.2
+ */
 int
 hex_document_compare_data_full (HexDocument *doc,
                HexDocumentFindData *find_data,
@@ -1218,6 +1234,23 @@ hex_document_compare_data (HexDocument *doc,
        return retval;
 }
 
+/**
+ * hex_document_find_forward_full:
+ * @find_data: a #HexDocumentFindData structure
+ *
+ * Full version of [method@Hex.Document.find_forward] which allows for
+ * more flexibility than the above, which is only for a byte-by-byte exact
+ * match. However, it is less convenient to call since the caller must
+ * create and and free a #HexDocumentFindData structure manually.
+ *
+ * This method will block. For a non-blocking version, use
+ * [method@Hex.Document.find_forward_async].
+ *
+ * Returns: %TRUE if the search string contained in `find_data` was found by
+ *   the requested operation; %FALSE otherwise.
+ *
+ * Since: 4.2
+ */
 gboolean
 hex_document_find_forward_full (HexDocument *doc,
                HexDocumentFindData *find_data)
@@ -1352,10 +1385,20 @@ FUNC_NAME (HexDocument *doc, \
        g_task_run_in_thread (task, FUNC_TO_CALL); \
 }
 
+/**
+ * hex_document_find_forward_full_async:
+ * @find_data: a #HexDocumentFindData structure
+ * @cancellable: (nullable): a #GCancellable
+ * @callback: (scope async): function to be called when the operation is
+ *   complete
+ *
+ * Non-blocking version of [method@Hex.Document.find_forward_full].
+ *
+ * Since: 4.2
+ */
 FIND_FULL_ASYNC_TEMPLATE(hex_document_find_forward_full_async, 
                hex_document_find_forward_full_thread)
 
-/* CROSSREF: hex-document.h - HexDocumentFindData */
 /**
  * hex_document_find_forward_async:
  * @doc: a [class@Hex.Document] object
@@ -1408,6 +1451,23 @@ FUNC_NAME (HexDocument *doc, \
 FIND_ASYNC_TEMPLATE(hex_document_find_forward_async,
                hex_document_find_forward_thread)
 
+/**
+ * hex_document_find_backward_full:
+ * @find_data: a #HexDocumentFindData structure
+ *
+ * Full version of [method@Hex.Document.find_backward] which allows for
+ * more flexibility than the above, which is only for a byte-by-byte exact
+ * match. However, it is less convenient to call since the caller must
+ * create and and free a #HexDocumentFindData structure manually.
+ *
+ * This method will block. For a non-blocking version, use
+ * [method@Hex.Document.find_backward_full_async].
+ *
+ * Returns: %TRUE if the search string contained in `find_data` was found by
+ *   the requested operation; %FALSE otherwise.
+ *
+ * Since: 4.2
+ */
 gboolean
 hex_document_find_backward_full (HexDocument *doc,
                HexDocumentFindData *find_data)
@@ -1486,6 +1546,17 @@ hex_document_find_backward_thread (GTask *task,
        g_task_return_pointer (task, find_data, g_free);
 }
 
+/**
+ * hex_document_find_backward_full_async:
+ * @find_data: a #HexDocumentFindData structure
+ * @cancellable: (nullable): a #GCancellable
+ * @callback: (scope async): function to be called when the operation is
+ *   complete
+ *
+ * Non-blocking version of [method@Hex.Document.find_backward_full].
+ *
+ * Since: 4.2
+ */
 FIND_FULL_ASYNC_TEMPLATE(hex_document_find_backward_full_async,
                hex_document_find_backward_full_thread)
 
@@ -1503,7 +1574,7 @@ FIND_FULL_ASYNC_TEMPLATE(hex_document_find_backward_full_async,
  *   is not found
  * @callback: (scope async): function to be called when the operation is
  *   complete
- * 
+ *
  * Non-blocking version of [method@Hex.Document.find_backward]. This is the
  * function that should generally be used by a GUI client to find a string
  * backwards in a #HexDocument.
diff --git a/src/hex-document.h b/src/hex-document.h
index 1dc238c..be627ea 100644
--- a/src/hex-document.h
+++ b/src/hex-document.h
@@ -55,6 +55,16 @@ typedef enum
        HEX_CHANGE_BYTE
 } HexChangeType;
 
+/**
+ * HexSearchFlags:
+ * @HEX_SEARCH_NONE: no search flags (byte-for-byte match)
+ * @HEX_SEARCH_REGEX: regular expression search
+ * @HEX_SEARCH_IGNORE_CASE: case-insensitive search
+ *
+ * Bitwise flags for search options that can be combined as desired.
+ *
+ * Since: 4.2
+ */
 typedef enum
 {
        HEX_SEARCH_NONE                         = 0,
@@ -69,7 +79,10 @@ typedef enum
  * @what: (array length=len): a pointer to the data to search within the
  *   #HexDocument
  * @len: length in bytes of the data to be searched for
+ * @flags: [enum@Hex.SearchFlags] search flags (Since: 4.2)
  * @offset: offset of the found string
+ * @found_len: length of the found string (may be different from the search
+ *   string when dealing with regular expressions, for example) (Since: 4.2)
  * @found_msg: message intended to be displayed by the client if the string
  *   is found
  * @not_found_msg: message intended to be displayed by the client if the string
@@ -87,9 +100,9 @@ typedef struct
        gint64 start;
        const char *what;
        size_t len;
-       HexSearchFlags flags;   /* TODO: Since: 4.1 */
+       HexSearchFlags flags;
        gint64 offset;
-       size_t found_len;               /* TODO: Since: 4.1 */
+       size_t found_len;
        const char *found_msg;
        const char *not_found_msg;
 } HexDocumentFindData;