From 017b6fe4b3e23955f8ef8cf5ac03f196d23f19f1 Mon Sep 17 00:00:00 2001
From: "Dustin J. Mitchell" <djmitche@google.com>
Date: Mon, 25 Dec 2023 18:58:24 -0500
Subject: [PATCH] add forward declaration for TCTaskList

---
 taskchampion/lib/src/lib.rs     |  5 +++--
 taskchampion/lib/src/replica.rs | 40 ++++++++++++++++++++-------------
 taskchampion/lib/taskchampion.h |  7 ++++--
 3 files changed, 32 insertions(+), 20 deletions(-)

diff --git a/taskchampion/lib/src/lib.rs b/taskchampion/lib/src/lib.rs
index 5bd7b9fdf..85a2e0524 100644
--- a/taskchampion/lib/src/lib.rs
+++ b/taskchampion/lib/src/lib.rs
@@ -49,8 +49,9 @@ ffizz_header::snippet! {
 ///
 /// It also defines a few utility types:
 ///
-///  * TCString - a wrapper around both C (NUL-terminated) and Rust (always utf-8) strings.  *
-///  TC…List - a list of objects represented as a C array * see below for the remainder
+///  * TCString - a wrapper around both C (NUL-terminated) and Rust (always utf-8) strings. 
+///  * TC…List - a list of objects represented as a C array
+///  * see below for the remainder
 ///
 /// # Safety
 ///
diff --git a/taskchampion/lib/src/replica.rs b/taskchampion/lib/src/replica.rs
index 390d45179..9f1bb4305 100644
--- a/taskchampion/lib/src/replica.rs
+++ b/taskchampion/lib/src/replica.rs
@@ -130,8 +130,16 @@ where
     }
 }
 
+// Include a forward definition for TCTaskList, as functions here return that type.
+ffizz_header::snippet! {
+#[ffizz(name="TCTaskListForward", order = 901)]
+/// ```c
+/// struct TCTaskList;
+/// ```
+}
+
 #[ffizz_header::item]
-#[ffizz(order = 901)]
+#[ffizz(order = 902)]
 /// Create a new TCReplica with an in-memory database.  The contents of the database will be
 /// lost when it is freed with tc_replica_free.
 ///
@@ -149,7 +157,7 @@ pub unsafe extern "C" fn tc_replica_new_in_memory() -> *mut TCReplica {
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 901)]
+#[ffizz(order = 902)]
 /// Create a new TCReplica with an on-disk database having the given filename.  On error, a string
 /// is written to the error_out parameter (if it is not NULL) and NULL is returned.  The caller
 /// must free this string.
@@ -187,7 +195,7 @@ pub unsafe extern "C" fn tc_replica_new_on_disk(
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Get a list of all tasks in the replica.
 ///
 /// Returns a TCTaskList with a NULL items field on error.
@@ -226,7 +234,7 @@ pub unsafe extern "C" fn tc_replica_all_tasks(rep: *mut TCReplica) -> TCTaskList
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Get a list of all uuids for tasks in the replica.
 ///
 /// Returns a TCUuidList with a NULL items field on error.
@@ -257,7 +265,7 @@ pub unsafe extern "C" fn tc_replica_all_task_uuids(rep: *mut TCReplica) -> TCUui
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Get the current working set for this replica.  The resulting value must be freed
 /// with tc_working_set_free.
 ///
@@ -281,7 +289,7 @@ pub unsafe extern "C" fn tc_replica_working_set(rep: *mut TCReplica) -> *mut TCW
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Get an existing task by its UUID.
 ///
 /// Returns NULL when the task does not exist, and on error.  Consult tc_replica_error
@@ -312,7 +320,7 @@ pub unsafe extern "C" fn tc_replica_get_task(rep: *mut TCReplica, tcuuid: TCUuid
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Create a new task.  The task must not already exist.
 ///
 /// Returns the task, or NULL on error.
@@ -345,7 +353,7 @@ pub unsafe extern "C" fn tc_replica_new_task(
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Create a new task.  The task must not already exist.
 ///
 /// Returns the task, or NULL on error.
@@ -375,7 +383,7 @@ pub unsafe extern "C" fn tc_replica_import_task_with_uuid(
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Synchronize this replica with a server.
 ///
 /// The `server` argument remains owned by the caller, and must be freed explicitly.
@@ -407,7 +415,7 @@ pub unsafe extern "C" fn tc_replica_sync(
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Undo local operations until the most recent UndoPoint.
 ///
 /// If undone_out is not NULL, then on success it is set to 1 if operations were undone, or 0 if
@@ -435,7 +443,7 @@ pub unsafe extern "C" fn tc_replica_undo(rep: *mut TCReplica, undone_out: *mut i
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Get the number of local, un-synchronized operations (not including undo points), or -1 on
 /// error.
 ///
@@ -455,7 +463,7 @@ pub unsafe extern "C" fn tc_replica_num_local_operations(rep: *mut TCReplica) ->
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Get the number of undo points (number of undo calls possible), or -1 on error.
 ///
 /// ```c
@@ -474,7 +482,7 @@ pub unsafe extern "C" fn tc_replica_num_undo_points(rep: *mut TCReplica) -> i64
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Add an UndoPoint, if one has not already been added by this Replica.  This occurs automatically
 /// when a change is made.  The `force` flag allows forcing a new UndoPoint even if one has already
 /// been created by this Replica, and may be useful when a Replica instance is held for a long time
@@ -496,7 +504,7 @@ pub unsafe extern "C" fn tc_replica_add_undo_point(rep: *mut TCReplica, force: b
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Rebuild this replica's working set, based on whether tasks are pending or not.  If `renumber`
 /// is true, then existing tasks may be moved to new working-set indices; in any case, on
 /// completion all pending tasks are in the working set and all non- pending tasks are not.
@@ -520,7 +528,7 @@ pub unsafe extern "C" fn tc_replica_rebuild_working_set(
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 902)]
+#[ffizz(order = 903)]
 /// Get the latest error for a replica, or a string with NULL ptr if no error exists.  Subsequent
 /// calls to this function will return NULL.  The rep pointer must not be NULL.  The caller must
 /// free the returned string.
@@ -546,7 +554,7 @@ pub unsafe extern "C" fn tc_replica_error(rep: *mut TCReplica) -> TCString {
 }
 
 #[ffizz_header::item]
-#[ffizz(order = 903)]
+#[ffizz(order = 904)]
 /// Free a replica.  The replica may not be used after this function returns and must not be freed
 /// more than once.
 ///
diff --git a/taskchampion/lib/taskchampion.h b/taskchampion/lib/taskchampion.h
index 82cabdd8e..d34f5f3f8 100644
--- a/taskchampion/lib/taskchampion.h
+++ b/taskchampion/lib/taskchampion.h
@@ -17,8 +17,9 @@
 //
 // It also defines a few utility types:
 //
-//  * TCString - a wrapper around both C (NUL-terminated) and Rust (always utf-8) strings.  *
-//  TC…List - a list of objects represented as a C array * see below for the remainder
+//  * TCString - a wrapper around both C (NUL-terminated) and Rust (always utf-8) strings. 
+//  * TC…List - a list of objects represented as a C array
+//  * see below for the remainder
 //
 // # Safety
 //
@@ -467,6 +468,8 @@ EXTERN_C void tc_server_free(struct TCServer *server);
 // TCReplicas are not threadsafe.
 typedef struct TCReplica TCReplica;
 
+struct TCTaskList;
+
 // Create a new TCReplica with an in-memory database.  The contents of the database will be
 // lost when it is freed with tc_replica_free.
 EXTERN_C struct TCReplica *tc_replica_new_in_memory(void);