docs: Clean up both public and internal docs. (#222)

src/path/sentry_path_unix.c

@@ -259,6 +259,17 @@ sentry__path_clone(const sentry_path_t *path)
     return rv;
 }
 
+#define EINTR_RETRY(X, Y)                                                      \
+    do {                                                                       \
+        int _tmp;                                                              \
+        do {                                                                   \
+            _tmp = (X);                                                        \
+        } while (_tmp == -1 && errno == EINTR);                                \
+        if (Y != 0) {                                                          \
+            *(int *)Y = _tmp;                                                  \
+        }                                                                      \
+    } while (false)
+
 int
 sentry__path_remove(const sentry_path_t *path)
 {

src/sentry_alloc.h

@@ -3,6 +3,9 @@
 
 #include "sentry_boot.h"
 
+/**
+ * This is a shortcut for a typed `malloc`.
+ */
 #define SENTRY_MAKE(Type) (Type *)sentry_malloc(sizeof(Type))
 
 #endif

src/sentry_backend.h

@@ -5,6 +5,12 @@
 
 #include "sentry_scope.h"
 
+/**
+ * This represents the crash handling backend.
+ * It consists of a few hooks that integrate into the sentry lifecycle and which
+ * can ensure that any captured crash contains the sentry scope and other
+ * information.
+ */
 struct sentry_backend_s;
 typedef struct sentry_backend_s {
     void (*startup_func)(struct sentry_backend_s *);
@@ -19,7 +25,14 @@ typedef struct sentry_backend_s {
     void *data;
 } sentry_backend_t;
 
+/**
+ * This will free a previously allocated backend.
+ */
 void sentry__backend_free(sentry_backend_t *backend);
+
+/**
+ * Create a new backend, depending on build-time configuration.
+ */
 sentry_backend_t *sentry__backend_new(void);
 
 #endif

src/sentry_core.h

@@ -48,14 +48,21 @@
 
 struct sentry_backend_s;
 
-// We save the attachments as a linked list basically
+/**
+ * This is a linked list of all the attachments registered via
+ * `sentry_options_add_attachment`.
+ */
 typedef struct sentry_attachment_s sentry_attachment_t;
 struct sentry_attachment_s {
     char *name;
     sentry_path_t *path;
     sentry_attachment_t *next;
 };
 
+/**
+ * This is the main options struct, which is being accessed throughout all of
+ * the sentry internals.
+ */
 struct sentry_options_s {
     char *raw_dsn;
     sentry_dsn_t dsn;
@@ -84,15 +91,39 @@ struct sentry_options_s {
     sentry_user_consent_t user_consent;
 };
 
+/**
+ * This will free a previously allocated attachment.
+ */
 void sentry__attachment_free(sentry_attachment_t *attachment);
 
+/**
+ * This function will check the user consent, and return `true` if uploads
+ * should *not* be sent to the sentry server, and be discarded instead.
+ */
 bool sentry__should_skip_upload(void);
 
+/**
+ * This function is essential to capture reports in the case of a hard crash.
+ * It will set a special transport that will dump events to disk.
+ * See `sentry__run_write_envelope`.
+ */
 void sentry__enforce_disk_transport(void);
 
+/**
+ * This function will submit the given `envelope` to the configured transport.
+ */
 void sentry__capture_envelope(sentry_envelope_t *envelope);
 
+/**
+ * Generates a new random UUID for events.
+ */
 sentry_uuid_t sentry__new_event_id(void);
+
+/**
+ * This will ensure that the given `event` has a UUID, generating a new one on
+ * demand. It will return a serialized UUID as `sentry_value_t` and also write
+ * it into the `uuid_out` parameter.
+ */
 sentry_value_t sentry__ensure_event_id(
     sentry_value_t event, sentry_uuid_t *uuid_out);
 

src/sentry_database.h

@@ -13,25 +13,61 @@ typedef struct {
     sentry_filelock_t *lock;
 } sentry_run_t;
 
+/**
+ * This creates a new application run including its associated directory and
+ * lockfile:
+ * * `<database>/<uuid>.run/`
+ * * `<database>/<uuid>.run.lock`
+ */
 sentry_run_t *sentry__run_new(const sentry_path_t *database_path);
 
 /**
- * This will clean up all the files belonging to this to this run.
+ * This will clean up all the files belonging to this run.
  */
 void sentry__run_clean(sentry_run_t *run);
+
+/**
+ * Free the previously allocated run.
+ * Make sure to call `sentry__run_clean` first, to not leave any files or
+ * directories laying around.
+ */
 void sentry__run_free(sentry_run_t *run);
 
+/**
+ * This will serialize and write the given envelope to disk into a file named
+ * like so:
+ * `<database>/<uuid>.run/<event-uuid>.envelope`
+ */
 bool sentry__run_write_envelope(
     const sentry_run_t *run, const sentry_envelope_t *envelope);
+
+/**
+ * This will serialize and write the given session to disk into a file named:
+ * `<database>/<uuid>.run/session.json`
+ */
 bool sentry__run_write_session(
     const sentry_run_t *run, const sentry_session_t *session);
+
+/**
+ * This will remove any previously created session file.
+ * See `sentry__run_write_session`.
+ */
 bool sentry__run_clear_session(const sentry_run_t *run);
 
+/**
+ * This function is essential to send crash reports from previous runs of the
+ * program.
+ * More specifically, this function will iterate over all the  directories
+ * inside the `database_path`. Directories matching `<database>/<uuid>.run/`
+ * will be locked, and any files named  `<event-uuid>.envelope` or
+ * `session.json` will be queued for sending to the  backend. The files and
+ * directories matching these criteria will be deleted afterwards.
+ */
 void sentry__process_old_runs(const sentry_options_t *options);
 
 /**
- * This will write the current timestamp (ISO formatted) into the
- * `${database_path}/last_crash` file.
+ * This will write the current ISO8601 formatted timestamp into the
+ * `<database>/last_crash` file.
  */
 bool sentry__write_crash_marker(const sentry_options_t *options);
 

src/sentry_envelope.h

@@ -19,6 +19,9 @@ typedef struct sentry_prepared_http_header_s {
     char *value;
 } sentry_prepared_http_header_t;
 
+/**
+ * This represents a HTTP request, with method, url, headers and a body.
+ */
 typedef struct sentry_prepared_http_request_s {
     char *url;
     const char *method;
@@ -29,34 +32,94 @@ typedef struct sentry_prepared_http_request_s {
     bool payload_owned;
 } sentry_prepared_http_request_t;
 
+/**
+ * Free a previously allocated HTTP request.
+ */
 void sentry__prepared_http_request_free(sentry_prepared_http_request_t *req);
 
+/**
+ * Create a new empty envelope.
+ */
 sentry_envelope_t *sentry__envelope_new(void);
+
+/**
+ * This loads a previously serialized envelope from disk.
+ */
 sentry_envelope_t *sentry__envelope_from_path(const sentry_path_t *path);
+
+/**
+ * This returns the UUID of the event associated with this envelope.
+ * If there is no event inside this envelope, or the envelope was previously
+ * loaded from disk, the empty nil UUID will be returned.
+ */
 sentry_uuid_t sentry__envelope_get_event_id(const sentry_envelope_t *envelope);
+
+/**
+ * Add an event to this envelope.
+ */
 sentry_envelope_item_t *sentry__envelope_add_event(
     sentry_envelope_t *envelope, sentry_value_t event);
+
+/**
+ * Add a session to this envelope.
+ */
 sentry_envelope_item_t *sentry__envelope_add_session(
     sentry_envelope_t *envelope, const sentry_session_t *session);
+
+/**
+ * This will add the file contents from `path` as an envelope item of type
+ * `type`.
+ */
 sentry_envelope_item_t *sentry__envelope_add_from_path(
     sentry_envelope_t *envelope, const sentry_path_t *path, const char *type);
+
+/**
+ * This will add the given buffer as a new envelope item of type `type`.
+ */
 sentry_envelope_item_t *sentry__envelope_add_from_buffer(
     sentry_envelope_t *envelope, const char *buf, size_t buf_len,
     const char *type);
+
+/**
+ * This sets an explicit header for the given envelope item.
+ */
 void sentry__envelope_item_set_header(
     sentry_envelope_item_t *item, const char *key, sentry_value_t value);
+
+/**
+ * This will call the provided `callback` once for each HTTP request that an
+ * envelope generates. The callback will be called zero or more times, depending
+ * on the envelope items, and the rate limits enforced by `rl`. Rate limited
+ * items will be skipped.
+ */
 void sentry__envelope_for_each_request(const sentry_envelope_t *envelope,
     bool (*callback)(sentry_prepared_http_request_t *,
         const sentry_envelope_t *, void *data),
     const struct sentry_rate_limiter_s *rl, void *data);
 
+/**
+ * Serialize the envelope header into the given string builder.
+ */
 void sentry__envelope_serialize_headers_into_stringbuilder(
     const sentry_envelope_t *envelope, sentry_stringbuilder_t *sb);
+
+/**
+ * Serialize a single envelope item into the given string builder.
+ */
 void sentry__envelope_serialize_item_into_stringbuilder(
     const sentry_envelope_item_t *item, sentry_stringbuilder_t *sb);
+
+/**
+ * Serialize a complete envelope with all its items into the given string
+ * builder.
+ */
 void sentry__envelope_serialize_into_stringbuilder(
     const sentry_envelope_t *envelope, sentry_stringbuilder_t *sb);
 
+/**
+ * Serialize the envelope, and write it to a new file at `path`.
+ * The envelope can later be loaded using `sentry__envelope_from_path`.
+ */
 MUST_USE int sentry_envelope_write_to_path(
     const sentry_envelope_t *envelope, const sentry_path_t *path);
 

src/sentry_json.h

@@ -6,25 +6,92 @@
 struct sentry_jsonwriter_s;
 typedef struct sentry_jsonwriter_s sentry_jsonwriter_t;
 
+/**
+ * This creates a new in-memory JSON writer, based on `sentry_stringbuilder_s`.
+ */
 sentry_jsonwriter_t *sentry__jsonwriter_new_in_memory(void);
+
+/**
+ * Deallocates a JSON writer.
+ */
 void sentry__jsonwriter_free(sentry_jsonwriter_t *jw);
+
+/**
+ * This will consume and deallocate the JSON writer, returning the generated
+ * JSON string, and writing its length into `len_out`.
+ */
 char *sentry__jsonwriter_into_string(sentry_jsonwriter_t *jw, size_t *len_out);
 
+/**
+ * Write a `null` into the JSON.
+ */
 void sentry__jsonwriter_write_null(sentry_jsonwriter_t *jw);
+
+/**
+ * Write a JSON boolean.
+ */
 void sentry__jsonwriter_write_bool(sentry_jsonwriter_t *jw, bool val);
+
+/**
+ * Write a 32-bit number, which will be encoded in a JSON number.
+ */
 void sentry__jsonwriter_write_int32(sentry_jsonwriter_t *jw, int32_t val);
+
+/**
+ * Write a 64-bit float, encoded as JSON number.
+ */
 void sentry__jsonwriter_write_double(sentry_jsonwriter_t *jw, double val);
+
+/**
+ * Write a zero-terminated string.
+ */
 void sentry__jsonwriter_write_str(sentry_jsonwriter_t *jw, const char *val);
+
+/**
+ * Write a UUID as a JSON string.
+ * See `sentry_uuid_as_string`.
+ */
 void sentry__jsonwriter_write_uuid(
     sentry_jsonwriter_t *jw, const sentry_uuid_t *uuid);
+
+/**
+ * This will write a millisecond resolution timestamp formattad as an ISO8601
+ * string.
+ * See `sentry__msec_time_to_iso8601`.
+ */
 void sentry__jsonwriter_write_msec_timestamp(
     sentry_jsonwriter_t *jw, uint64_t time);
+
+/**
+ * Writes the *Key* part of an object Key-Value pair.
+ */
 void sentry__jsonwriter_write_key(sentry_jsonwriter_t *jw, const char *val);
+
+/**
+ * Start a new JSON array.
+ * Needs to be closed with `sentry__jsonwriter_write_list_end`.
+ */
 void sentry__jsonwriter_write_list_start(sentry_jsonwriter_t *jw);
+
+/**
+ * End the previously started JSON array.
+ */
 void sentry__jsonwriter_write_list_end(sentry_jsonwriter_t *jw);
+
+/**
+ * Start a new JSON object.
+ * Needs to be closed with `sentry__jsonwriter_write_object_end`.
+ */
 void sentry__jsonwriter_write_object_start(sentry_jsonwriter_t *jw);
+
+/**
+ * End the previously started JSON object.
+ */
 void sentry__jsonwriter_write_object_end(sentry_jsonwriter_t *jw);
 
+/**
+ * Parse the given JSON string into a new Value.
+ */
 sentry_value_t sentry__value_from_json(const char *buf, size_t buflen);
 
 #endif

src/sentry_modulefinder.h

@@ -3,8 +3,16 @@
 
 #include "sentry_boot.h"
 
+/**
+ * This will lazily load and cache a list of all the loaded modules.
+ * The returned value is borrowed.
+ */
 sentry_value_t sentry__modules_get_list(void);
 
+/**
+ * This will clean up the internal module cache. The list will be lazily loaded
+ * again on the next call to `sentry__modules_get_list`.
+ */
 void sentry__modulefinder_cleanup(void);
 
 #endif