I've seen crates like that: APIs with very complex trait bounds that require one to sit down with a cup of tea to pour over before you can understand what they do. I don't particularly like those. What APIs written that way enable is that you're forced to use them correctly, you have a bunch of type ceremony that you need to follow before the compiler will accept a simple method call. That means that the API is resistant to misuse. What you are asking for, reasonably, is for the opposite situation: give me enough information that if I'm accidentally misusing the API, which will be rejected, I will be able to understand what's missing so that I can use it correctly.

I'm personally of the opinion that crate author should provide explanations, examples, and take into account the kind of compiler errors people will get when they inevitably try to misuse the APIs.

Just use basic types?

Sure you can over engineer Rust, for dubious gains. But that's true for any language. *cough* MetaAbstractFactoryProxyFactoryFacadeBuilderProxySingletonWebViewFactory *cough*

> More self-documenting for whom

Anyone using basic Rust types.

Is type `Sync`? It's safe to share between threads.

Is type `Option` its value can be missing i.e. None.

Is type moved? Yes, if it isn't borrowed, and not Copy.

Isn’t that supposed to be a Bean?

We're talking about C code that has refcounted objects, where you have to know ahead of time to add or remove a refcount before you call specific C functions. In Rust that would just be an Rc or an Arc, and the programmer would not need specific knowledge.

Or a C function that either returns an existing object, or a new object that is incompletely initialized. If it is an existing object, you are required to call a second function to finish the initialization. And you’re just supposed to know about that requirement; it’s not documented anywhere. On the Rust side they decided to return an Either<EmptyObject, InitializedObject> instead, so that the programmer can directly see what is going on.

They’re not saying that all Rust APIs are immediately easy to understand, only that they require less manually–written documentation because the constraints can be encoded into the type system.