docs again

Author: nia-e

src/shims/trace/messages.rs

@@ -3,13 +3,20 @@
 //! The overall structure of a traced FFI call, from the child process's POV, is
 //! as follows:
 //! ```
-//! message_tx.send(TraceRequest::StartFFI);
+//! message_tx.send(TraceRequest::StartFfi);
 //! confirm_rx.recv();
 //! raise(SIGSTOP);
 //! /* do ffi call */
-//! raise(SIGUSR1);
+//! raise(SIGUSR1); // morally equivalent to some kind of "TraceRequest::EndFfi"
 //! let events = event_rx.recv();
 //! ```
+//! `TraceRequest::OverrideRetcode` can be sent at any point in the above, including
+//! before or after all of them.
+//! 
+//! NB: sending these events out of order, skipping steps, etc. will result in
+//! unspecified behaviour from the supervisor process, so use the abstractions
+//! in `super::child` (namely `start_ffi()` and `end_ffi()`) to handle this. It is
+//! trivially easy to cause a deadlock or crash by messing this up!
 
 /// An IPC request sent by the child process to the parent.
 ///
@@ -36,7 +43,7 @@ pub(super) enum TraceRequest {
 pub(super) struct Confirmation;
 
 /// The final results of an FFI trace, containing every relevant event detected
-/// by the tracer. Sent by the supervisor.
+/// by the tracer. Sent by the supervisor after receiving a `SIGUSR1` signal.
 ///
 /// The sender for this channel should live on the parent process.
 #[derive(serde::Serialize, serde::Deserialize, Debug)]