From 42a08bfb89e3bf171a00ca0ffb20bc370ca090fe Mon Sep 17 00:00:00 2001
From: ChadliaJerad <chadlia.jerad@gmail.com>
Date: Thu, 8 Jun 2023 10:46:29 -0700
Subject: [PATCH] Code review: Add logical_tag_complete documentation.

---
 core/federated/RTI/enclave.h | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/core/federated/RTI/enclave.h b/core/federated/RTI/enclave.h
index 4bcc7b5a8..5637306ba 100644
--- a/core/federated/RTI/enclave.h
+++ b/core/federated/RTI/enclave.h
@@ -76,14 +76,19 @@ typedef struct enclave_RTI_t {
     // Number of enclaves handling stop
     int num_enclaves_handling_stop;
 
-    /**
-     * Boolean indicating that tracing is enabled.
-     */
+    // Boolean indicating that tracing is enabled.
     bool tracing_enabled;
 } enclave_RTI_t;
 
 
-// FIXME: Docs
+/**
+ * An enclave calls this function after it completed a tag. 
+ * The function updates the completed tag and check if the downstream enclaves 
+ * are eligible for receiving TAGs.
+ * 
+ * @param enclave The enclave
+ * @param completed The completed tag of the enclave
+ */
 void logical_tag_complete(enclave_t* enclave, tag_t completed);
 
 typedef struct {
@@ -93,6 +98,8 @@ typedef struct {
 
 /** 
  * Initialize the enclave with the specified ID.
+ * 
+ * @param e The enclave
  * @param id The enclave ID.
  */
 void initialize_enclave(enclave_t* e, uint16_t id);
@@ -179,7 +186,9 @@ void notify_provisional_tag_advance_grant(enclave_t* e, tag_t tag);
  *
  * This function assumes that the caller holds the mutex lock.
  *
- * @return True if the TAG message is sent and false otherwise.
+ * @param e The enclave
+ * @return If granted, return the tag value and whether it is provisional. 
+ *  Otherwise, return the NEVER_TAG.
  */
 tag_advance_grant_t tag_advance_grant_if_safe(enclave_t* e);
 
@@ -196,6 +205,8 @@ tag_advance_grant_t tag_advance_grant_if_safe(enclave_t* e);
  *
  * @param e The enclave.
  * @param next_event_tag The next event tag for e.
+ * @return If granted, return the TAG and whether it is provisional or not. 
+ *  Otherwise, return the NEVER_TAG.
  */
 tag_advance_grant_t next_event_tag(enclave_t* e, tag_t next_event_tag);
 
@@ -226,12 +237,13 @@ void update_enclave_next_event_tag_locked(enclave_t* e, tag_t next_event_tag);
  * which outputs can be triggered by which inputs. For now, we
  * assume any output can be triggered by any input.
  *
- * @param fed The federate.
+ * @param e The enclave.
  * @param candidate A candidate tag (for the first invocation,
  *  this should be fed->next_event).
  * @param visited An array of booleans indicating which federates
  *  have been visited (for the first invocation, this should be
  *  an array of falses of size _RTI.number_of_federates).
+ * @return The earliest next event tag of the enclave e.
  */
 tag_t transitive_next_event(enclave_t *e, tag_t candidate, bool visited[]);