Document situation with error replies

crates/amalthea/src/socket/shell.rs

@@ -232,6 +232,8 @@ impl Shell {
                 let r = req.send_reply(reply, &self.socket);
                 r
             },
+            // FIXME: Ark already created an `ExecuteReplyException` so we use
+            // `.send_reply()` instead of `.send_error()`. Can we streamline this?
             Err(err) => req.send_reply(err, &self.socket),
         }
     }

crates/amalthea/src/wire/error_reply.rs

@@ -13,7 +13,11 @@ use crate::wire::jupyter_message::MessageType;
 use crate::wire::jupyter_message::Status;
 
 /// Represents an error that occurred after processing a request on a
-/// ROUTER/DEALER socket
+/// ROUTER/DEALER socket.
+///
+/// This is the payload of a response to a request. Note that, as an exception,
+/// responses to `"execute_request"` include an `execution_count` field. We
+/// represent these with an `ExecuteReplyException`.
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct ErrorReply {
     /// The status; always Error
@@ -25,9 +29,11 @@ pub struct ErrorReply {
 }
 
 /// Note that the message type of an error reply is generally adjusted to match
-/// its request type (e.g. foo_request => foo_reply)
+/// its request type (e.g. foo_request => foo_reply). The message type
+/// implemented here is only a placeholder and should not appear in any
+/// serialized/deserialized message.
 impl MessageType for ErrorReply {
     fn message_type() -> String {
-        String::from("error")
+        String::from("*error payload*")
     }
 }

crates/amalthea/src/wire/execute_error.rs

@@ -11,7 +11,10 @@ use serde::Serialize;
 use crate::wire::exception::Exception;
 use crate::wire::jupyter_message::MessageType;
 
-/// Represents an exception that occurred while executing code
+/// Represents an exception that occurred while executing code.
+/// This is sent to IOPub. Not to be confused with `ExecuteReplyException`
+/// which is a special case of a message of type `"execute_reply"` sent to Shell
+/// in response to an `"execute_request"`.
 #[derive(Debug, Serialize, Deserialize, Clone)]
 pub struct ExecuteError {
     /// The exception that occurred during execution