diff --git a/include/sentry.h b/include/sentry.h
index 91146520a9..61c4c3f222 100644
--- a/include/sentry.h
+++ b/include/sentry.h
@@ -469,9 +469,12 @@ typedef struct sentry_ucontext_s {
  *
  * If the address is given in `addr` the stack is unwound form there.
  * Otherwise (NULL is passed) the current instruction pointer is used as
- * start address. The stack trace is written to `stacktrace_out` with up to
- * `max_len` frames being written.  The actual number of unwound stackframes
- * is returned.
+ * start address.
+ * Unwinding with a given `addr` is not supported on all platforms.
+ *
+ * The stack trace in the form of instruction-addresses, is written to the
+ * caller allocated `stacktrace_out`, with up to `max_len` frames being written.
+ * The actual number of unwound stackframes is returned.
  */
 SENTRY_EXPERIMENTAL_API size_t sentry_unwind_stack(
     void *addr, void **stacktrace_out, size_t max_len);
@@ -479,8 +482,12 @@ SENTRY_EXPERIMENTAL_API size_t sentry_unwind_stack(
 /**
  * Unwinds the stack from the given context.
  *
- * The stack trace is written to `stacktrace_out` with up to `max_len` frames
- * being written.  The actual number of unwound stackframes is returned.
+ * The caller is responsible to construct an appropriate `sentry_ucontext_t`.
+ * Unwinding from a user context is not supported on all platforms.
+ *
+ * The stack trace in the form of instruction-addresses, is written to the
+ * caller allocated `stacktrace_out`, with up to `max_len` frames being written.
+ * The actual number of unwound stackframes is returned.
  */
 SENTRY_EXPERIMENTAL_API size_t sentry_unwind_stack_from_ucontext(
     const sentry_ucontext_t *uctx, void **stacktrace_out, size_t max_len);