From 235cd254ca941725e3e4b6abf91eabf66c50e3cb Mon Sep 17 00:00:00 2001 From: Ian Jackson Date: Tue, 1 Feb 2022 16:51:34 +0000 Subject: [PATCH] docs/Errors.md: Say where error type is printed --- doc/Errors.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/doc/Errors.md b/doc/Errors.md index 298521015..67bc3a12b 100644 --- a/doc/Errors.md +++ b/doc/Errors.md @@ -173,6 +173,29 @@ For example, when tor-circmgr calls `build_channel`, it is tor-circmgr which is } ``` +#### Describing the error type + +When a problem is reported, different error types should generally produce different messages. Where should this be done ? + +Answer: the place where the type is embedded. For example: + +``` + enum tor_circmgr::Error { + /// Problem with channel + #[error("Problem with channel to {peer}")] + ChanFailed { + cause: tor_chanmgr::Error, + + enum tor_chanmgr::Error { + /// Network IO error or TLS error + #[error("Network IO error, or TLS error, talking to {peer}")] + Io { + /// Who we were talking to + peer: SocketAddr, +``` + +So the channel error does not say that it *is* a channel error, just as an `io::Error` doesn't say that it is an IO error. `tor_chanmgr::Error::Io` says that it is an IO error; when that is found inside eg a `tor_circmgr::Error`, the circmgr error is responsible for saying it's about a channel (and describing relevant channel properties). + ### In a new tor-errorkind crate