Would you guys find this feature useful for cargo docs?

As I've been learning alot this past half year about Rust, I have been converging to a deeper understanding that lets me "go with the flow" and simultaneously lay-down some code. There are times wherein expanding a metaphor in my mind and translating it into code, I must use unsafe code to implement the idea. I feel like what I'll propose will be very useful to have in cargo doc's HTML compiler.

Code-comments denoted within /// <my-text> should have an extension similar to this to denote contracts with unsafe functions (e.g., think of the Pin contract):

/// ~Contract~: You cannot move or replace the owned T out of the returned heap-pinned T
/// ~Contract~: [other requirements]...
/// ~Contract~: [more reqs...]
unsafe fn pin_box<T>(item: T) -> Pin<Box<T>> {
   Pin::new_unchecked(Box::new(item))
}

When cargo generates the HTML for it, the contract should be highlighted in red, and maybe with some caution symbols. By doing this, it would make it straightforward for API users to know what they can or can't do. We need this because, as we all know, just because the program compiles, it doesn't imply the behavior will be as expected. By having a contract-highlight feature for unsafe functions or traits, it will help coders be more diligent about how they think about their coding.

Because our imagination is infinite, but the domain of acceptable behavior is limited by binary when translating our imagination into code, making those limitations clear will be useful, especially for veterans who can skim these cautions and go "ah, that makes sense as to why this is a contract. Now I know what their code does under-the-hood without actually looking at it"

  • Yea
  • Nay

0 voters

Yeah, we could just use bullet points, but by creating a new view, we help embed the idea within the minds of the community that contracts are very important and should be an idea that is isolated from just normal text. Importance through differentiation

Well pin_box is just Box::pin, and your ~Contract~ tags are like # Safety sections on unsafe functions, which is a big bold new section that's hard to miss.

1 Like

Right, I originally had box::pin, then remembered that it wasn't unsafe. I just wanted something as a quick example.