api-guidelines
api-guidelines copied to clipboard
rust-lang
Rust API guidelines
Since [RFC3052](https://rust-lang.github.io/rfcs/3052-optional-authors-field.html), this field is effectively soft-deprecated, cargo no longer generates this field by default, and Rust's official services no longer reference this field at all.
The motivation for the [C-DEREF](https://rust-lang.github.io/api-guidelines/predictability.html#c-deref) guideline and the potential problems resulting from ignoring it are (imho) not self explaning. The strongest clue I can find is from the guideline being...
The guideline should make mention of defining a reasonable MSRV, how to go about doing so (explain how to install a specific Rust version using rustup and use it for...
C-DEREF unambiguously says that Deref is only for smart pointers. However I've noticed (via [this tweet](https://twitter.com/13erbse/status/1429848250354438148)) that there's another case where I reach out for Deref. It's not immediately clear...
The ship has flown the nest; `Deref` is not exclusively for smart pointers anymore. Fixes #249, the direct contradiction of C-DEREF with idiomatic std APIs.
C-WORD-ORDER requires that errors be named `VerbNounError`. However, this doesn't work for cases where there is no verb, for example in getters: ```rust impl Response { fn bytes(self) -> Result...
The table in C-CONV puts `Copy` types into `to_` category, which I believe is correct naming but at the same time says it's expensive conversion which is not the case...
For example, if we want to use structure fields or some [function](https://stackoverflow.com/questions/35536030/is-there-any-way-to-use-private-functions-in-public-macros-in-rust) inside a macro but don't want them to be part of the API, we mark them as hidden....
Since rust-lang/rust#43466 (intra-rustdoc links) was stabilized in [Rust 1.48](https://blog.rust-lang.org/2020/11/19/Rust-1.48.html#easier-linking-in-rustdoc), the information in [C-LINK](https://rust-lang.github.io/api-guidelines/documentation.html#prose-contains-hyperlinks-to-relevant-things-c-link) feels outdated, as it still suggests linking to other items manually rather than by making use of...
