I feel you misunderstood the thread if that's your take away.

The argument is that properly utilising a stronger type system is more self-documenting. And quite often to achieve safe abstractions, you have to lean into this paradigm more. It of course still requires discipline, but in my experience it works well in practice.

Since C has no generics/type templates, you cannot achieve the same level of type based abstractions, thus you cannot rely on the types semantics alone to suggest it's own use.

More self-documenting for whom, the code generating documentation? Because for using it as a programmer I've found the code that has been Rust-ified to normalize everything into 1000 traits of which the given type you are using might implement 100 you can't see without going into more documentation to be a nightmare.

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.

One great advantage of replacing comments with language constructs is that if the compiler checks the "docs", people don't forget to update it and can actually trust what's written down

"pour over" -> "pore over" btw

Thanks, I didn't know this. I suppose it's like writing "could of" instead of "could've" :)

That is not the point of the author. They clarify on reddit:

https://www.reddit.com/r/programming/comments/1f5qbhv/rust_s...

> This isn't a great title for the submission. Rust doesn't solve incomplete/missing docs in general (that is still a major problem when it comes to things like how subsystems are engineered and designed, and how they're meant to be used, including rules and patterns that are not encodable in the Rust type system and not related to soundness but rather correctness in other ways). What I meant is that kernel docs are specifically very often (almost always) incomplete in ways that relate to lifetimes, safety, borrowing, object states, error handling, optionality, etc., and Rust solves that.