[Analemma_]

Why bother having a typed return value? That could be in the documentation too. The whole point of a type system is to help me understand what the function can and cannot do without needing to make guesses based on the documentation. It's not fatal, but it is annoying and inconsistent that Rust can do this on the happy path but not the error path.

[lilyball]

The type system cannot capture 100% of the semantics of the function. You put what you can in there, but you also need documentation. You could provide a bespoke error type for every single function that returns an error, but that's a ton of boilerplate, and you're effectively just moving the documentation from the function to the error type (enum variant names are not sufficiently descriptive to avoid having to write documentation).

Even in cases where the error does already precisely match the semantics of the function, you still need documentation. std::sync::Mutex::lock() returns a `Result<MutexGuard<T>, PoisonError<MutexGuard<T>>>`. What's a PoisonError? That's a precise error type for the semantics of this function, but you need the documentation to tell you what it actually means for a mutex to be poisoned.

You cannot get away from having documentation. And you're free to make custom error types for all your functions if you want to, it just doesn't really get you much benefit over having a single unified error type for your module in most cases. If you have a reason to believe the caller actually does want to handle error variants differently then sure, make a new error type with just the variants that apply to this function, there's plenty of precedent for that (e.g. tokio::sync::mpsc::Sender has distinct error types for send() and try_send(), because that's a case where the caller actually may care about the precise reason), but most error values in Rust just end up getting propagated upwards and then eventually logged.

[brigadier132]

> You could provide a bespoke error type for every single function that returns an error, but that's a ton of boilerplate

If we had more typescript-like discriminated union semantics a lot of the boilerplate would go away. Throw in automatic implementation of From traits for enums composed of other enums / types and it could be pretty close to perfect.