Meta issue for Rust API Guidelines

[mcarton]

Let's see what makes sense to get into Clippy or not from the Rust API Guidelines.

Check the box if a lint or issue already exist for an item. See also is:issue is:open label:A-guidelines.

• Naming (crate aligns with Rust naming conventions)
  • Casing conforms to RFC 430 (C-CASE)
    • This is already covered by rustc's bad-style lint group.
  • Ad-hoc conversions follow as_, to_, into_ conventions (C-CONV)
  • Getter names follow Rust convention (C-GETTER)
  • Methods on collections that produce iterators follow iter, iter_mut, into_iter (C-ITER)
  • Iterator type names match the methods that produce them (C-ITER-TY)
    • Issue open: Rust API Guidelines: Iterator type names match the methods that produce them #1789
  • Feature names are free of placeholder words (C-FEATURE)
  • Names use a consistent word order (C-WORD-ORDER)
• Interoperability (crate interacts nicely with other library functionality)
  • Types eagerly implement common traits (C-COMMON-TRAITS)
    • Copy (rustc's missing-copy-implementations)
    • Clone
    • Eq
    • PartialEq
    • Ord
    • PartialOrd
    • Hash
    • Debug (rustc's missing-debug-implementations)
    • Display
    • Default (we do have new_without_default)
    • We already have that in some cases, but it's hard to determine if there is a good reason not to implement those from Clippy.
  • Conversions use the standard traits From, AsRef, AsMut (C-CONV-TRAITS)
    • Already covered as much as we can by SHOULD_IMPLEMENT_TRAIT.
    • Check that Into and TryInto are never implemented manually (only automatically via From)
  • Collections implement FromIterator and Extend (C-COLLECT)
    • issue open: Rust API Guidelines: Collections implement FromIterator and Extend #1801
  • Data structures implement Serde's Serialize, Deserialize (C-SERDE)
    • Clippy cannot know whether a type is a data structure or not.
  • Types are Send and Sync where possible (C-SEND-SYNC)
    • This is default, if people remove that, they must have a reason.
  • Error types are meaningful and well-behaved (C-GOOD-ERR)
  • Binary number types provide Hex, Octal, Binary formatting (C-NUM-FMT)
    • Clippy cannot know if a type is a binary number type or not.
  • Generic reader/writer functions take R: Read and W: Write by value (C-RW-VALUE)
• Macros (crate presents well-behaved macros)
  • Input syntax is evocative of the output (C-EVOCATIVE)
    • Too subjective.
  • Macros compose well with attributes (C-MACRO-ATTR)
    • Cannot lint on macros.
  • Item macros work anywhere that items are allowed (C-ANYWHERE)
    • Cannot lint on macros.
  • Item macros support visibility specifiers (C-MACRO-VIS)
    • Cannot lint on macros.
  • Type fragments are flexible (C-MACRO-TY)
    • Cannot lint on macros.
• Documentation (crate is abundantly documented)
  • Crate level docs are thorough and include examples (C-CRATE-DOC)
  • All items have a rustdoc example (C-EXAMPLE)
  • Examples use ?, not try!, not unwrap (C-QUESTION-MARK)
  • Function docs include error, panic, and safety considerations (C-FAILURE)
    • Issue open: Rust API Guideline: Function docs include error conditions in "Errors" section #1790
    • Issue open: Rust API Guideline: Function docs include panic conditions in "Panics" section #1791
    • Issue open: Rust API Guideline: Unsafe functions are documented with a "Safety" section #2207
  • Prose contains hyperlinks to relevant things (C-LINK)
  • Cargo.toml includes all common metadata (C-METADATA, clippy::cargo_common_metadata)
    • authors, description, license, homepage, documentation, repository,
      readme, keywords, categories
  • Crate sets html_root_url attribute "https://docs.rs/CRATE/X.Y.Z" (C-HTML-ROOT)
    • Issue open: Rust API Guideline: Crate sets html_root_url attribute #1788
  • Release notes document all significant changes (C-RELNOTES)
  • Rustdoc does not show unhelpful implementation details (C-HIDDEN)
• Predictability (crate enables legible code that acts how it looks)
  • Smart pointers do not add inherent methods (C-SMART-PTR)
  • Conversions live on the most specific type involved (C-CONV-SPECIFIC)
  • Functions with a clear receiver are methods (C-METHOD)
  • Functions do not take out-parameters (C-NO-OUT)
  • Operator overloads are unsurprising (C-OVERLOAD)
  • Only smart pointers implement Deref and DerefMut (C-DEREF)
  • Constructors are static, inherent methods (C-CTOR)
• Flexibility (crate supports diverse real-world use cases)
  • Functions expose intermediate results to avoid duplicate work (C-INTERMEDIATE)
  • Caller decides where to copy and place data (C-CALLER-CONTROL)
  • Functions minimize assumptions about parameters by using generics (C-GENERIC)
    • Issue open: Rust API Guideline: Functions minimize assumptions about parameters by using generics #1794
  • Traits are object-safe if they may be useful as a trait object (C-OBJECT)
• Type safety (crate leverages the type system effectively)
  • Newtypes provide static distinctions (C-NEWTYPE)
  • Arguments convey meaning through types, not bool or Option (C-CUSTOM-TYPE)
  • Types for a set of flags are bitflags, not enums (C-BITFLAG)
    • Issue open: Rust API Guidelines: Types for a set of flags are bitflags, not enums #1795
  • Builders enable construction of complex values (C-BUILDER)
• Dependability (crate is unlikely to do the wrong thing)
  • Functions validate their arguments (C-VALIDATE)
  • Destructors never fail (C-DTOR-FAIL)
  • Destructors that may block have alternatives (C-DTOR-BLOCK)
• Debuggability (crate is conducive to easy debugging)
  • All public types implement Debug (C-DEBUG)
    • Covered by rustc's missing-debug-implementations.
  • Debug representation is never empty (C-DEBUG-NONEMPTY)
    • Issue open: Rust API Guidelines: Debug representation is never empty #1796
• Future proofing (crate is free to improve without breaking users' code)
  • Sealed traits protect against downstream implementations (C-SEALED)
  • Structs have private fields (C-STRUCT-PRIVATE)
  • Newtypes encapsulate implementation details (C-NEWTYPE-HIDE)
  • Data structures do not duplicate derived trait bounds (C-STRUCT-BOUNDS)
• Necessities (to whom they matter, they really matter)
  • Public dependencies of a stable crate are stable (C-STABLE)
    • Issue open: Rust API Guidelines: Public dependencies of a stable crate are stable #1797
  • Crate and its dependencies have a permissive license (C-PERMISSIVE)
    • Clippy is not a lawyer.

[kennytm]

C-PANIC-DOC should point to #1791, C-DOCS-RS should point to #1788 or a new issue.

[killercup]

Nice work!

(You should use URLs with the commit hash in them (press y on github.com) so they continue to work in the future.)

[mcarton]

Thanks! I volontarily did not do that for this so that we point to the latest version of the guidelines. This might mean that we get broken links once in a while but that'll mean that the list here is outdated.

[clarfonthey]

Note that C-EXAMPLE is covered by #1454.

[mcarton]

Not quite, C-EXAMPLE is about not having an example, #1454 is about having a non-relevant example.

[killercup]

As predicted, the links no longer work. Now, how using links like this one instead?

[Susurrus]

Types eagerly implement common traits (C-COMMON-TRAITS)

rustc has missing-copy-implementations for Copy and missing-debug-implementations for Debug, but I don't see anything in rustc or clippy for any of the other traits:

• Clone
• Eq
• Ord
• PartialOrd
• Hash
• Display
• Default

This was checked off in the original checklist, so I wanted to double-check I wasn't missing anything.

[mcarton]

@Susurrus I split the list into sub-lists and unchecked the main item.

[philipcraig]

In the C-CONV-TRAITS subsection, could an editor please explicitly add a bullet "Into and TryInto are never implemented"?