docs: clarify behavior of sentry_flush + sentry_close (#883)

---------

Co-authored-by: Mischan Toosarani-Hausberger <mischan@abovevacant.com>

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## Unreleased
+
+**Thank you**:
+
+Features, fixes and improvements in this release have been contributed by:
+
+- [@sapphonie](https://github.com/sapphonie)
+
 ## 0.6.5
 
 **Fixes**:

include/sentry.h

@@ -1267,13 +1267,25 @@ SENTRY_API int sentry_init(sentry_options_t *options);
  * The `timeout` parameter is in milliseconds.
  *
  * Returns 0 on success, or a non-zero return value in case the timeout is hit.
+ *
+ * Note that this function will block the thread it was called from until the
+ * sentry background worker has finished its work or it timed out, whichever
+ * comes first.
  */
 SENTRY_API int sentry_flush(uint64_t timeout);
 
 /**
  * Shuts down the sentry client and forces transports to flush out.
  *
  * Returns 0 on success.
+ *
+ * Note that this does not uninstall any crash handler installed by our
+ * backends, which will still process crashes after `sentry_close()`, except
+ * when using `crashpad` on Linux or the `inproc` backend.
+ *
+ * Further note that this function will block the thread it was called from
+ * until the sentry background worker has finished its work or it timed out,
+ * whichever comes first.
  */
 SENTRY_API int sentry_close(void);