docs

toxcore/tox_events.h

@@ -29,12 +29,16 @@ uint32_t tox_events_get_friend_messages_size(const Tox_Events *events);
 const Tox_Event_Friend_Message *tox_events_get_friend_message(const Tox_Events *events, uint32_t index);
 
 /**
- * TODO(iphydf): Document.
+ * Initialise the events recording system.
+ *
+ * All callbacks will be set to handlers inside the events recording system.
+ * After this function returns, no user-defined event handlers will be
+ * invoked. If the client sets their own handlers after calling this function,
+ * the events associated with that handler will not be recorded.
  */
 void tox_events_init(Tox *tox);
 
 typedef enum Tox_Err_Events_Iterate {
-
     /**
      * The function returned successfully.
      */
@@ -48,16 +52,29 @@ typedef enum Tox_Err_Events_Iterate {
      * the function may have missed some events.
      */
     TOX_ERR_EVENTS_ITERATE_MALLOC,
-
 } Tox_Err_Events_Iterate;
 
 /**
- * TODO(iphydf): Document.
+ * Run a single `tox_iterate` iteration and record all the events.
+ *
+ * If allocation of the top level events object fails, this returns NULL.
+ * Otherwise it returns an object with the recorded events in it. If an
+ * allocation fails while recording events, some events may be dropped.
+ *
+ * The result must be freed using `tox_events_free`.
+ *
+ * @param tox The Tox instance to iterate on.
+ * @param error An error code. Will be set to OK on success.
+ *
+ * @returns the recorded events structure.
  */
 Tox_Events *tox_events_iterate(Tox *tox, Tox_Err_Events_Iterate *error);
 
 /**
- * TODO(iphydf): Document.
+ * Frees all memory associated with the events structure.
+ *
+ * All pointers into this object and its sub-objects, including byte buffers,
+ * will be invalid once this function returns.
  */
 void tox_events_free(Tox_Events *events);