Follow the Rust API Guidelines

[madsmtm]

Let's ensure that the library follows the official API guidelines (although I suspect it does on almost all accounts). I've posted the checklist below, and will try to fill it out as I see fit (opening issues for non-resolved items).

Rust API Guidelines Checklist

• Naming (crate aligns with Rust naming conventions)
  • Casing conforms to RFC 430 (C-CASE)
  • 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)
  • 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, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug,
      Display, Default
    • Note: For Copy, see Does RawWindowHandle need to be Copy? #138.
    • Note: Ordering traits would perhaps be ill-advised, as most of these are pointers, and the actual ordering would be rather unexpected?
    • Note: Display is probably undesired, since we don't pull in the libraries to give a proper description of the handles.
  • Conversions use the standard traits From, AsRef, AsMut (C-CONV-TRAITS)
  • Collections implement FromIterator and Extend (C-COLLECT)
  • Data structures implement Serde's Serialize, Deserialize (C-SERDE)
    • Note: Window handles cannot and should not be serialized or deserialized, especially not from disk; they are ephemeral, and very much tied to the lifetime of the program!
  • Types are Send and Sync where possible (C-SEND-SYNC)
    • Note: See Should RawWindowHandle implement Send? #85.
  • Error types are meaningful and well-behaved (C-GOOD-ERR)
    • Ensured by Add tests for Rust subleties #147
  • Binary number types provide Hex, Octal, Binary formatting (C-NUM-FMT)
  • 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)
  • Macros compose well with attributes (C-MACRO-ATTR)
  • Item macros work anywhere that items are allowed (C-ANYWHERE)
  • Item macros support visibility specifiers (C-MACRO-VIS)
  • Type fragments are flexible (C-MACRO-TY)
• Documentation (crate is abundantly documented)
  • Crate level docs are thorough and include examples (C-CRATE-DOC)
    • Moved to Improve documentation #149
  • All items have a rustdoc example (C-EXAMPLE)
    • Moved to Improve documentation #149
  • Examples use ?, not try!, not unwrap (C-QUESTION-MARK)
    • Moved to Improve documentation #149
  • Function docs include error, panic, and safety considerations (C-FAILURE)
    • Moved to Improve documentation #149
  • Prose contains hyperlinks to relevant things (C-LINK)
  • Cargo.toml includes all common metadata (C-METADATA)
    • authors, description, license, homepage, documentation, repository,
      keywords, categories
    • Note: Moved to Add relevant categories to Cargo.toml #148
  • 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)
  • 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)
  • Builders enable construction of complex values (C-BUILDER)
• Dependability (crate is unlikely to do the wrong thing)
  • Functions validate their arguments (C-VALIDATE)
    • Note: It's usually impossible to check if a pointer is valid, so we just have to assume it is; that's why it's unsafe!
    • Note: We could verify the integer handles, but that would introduce dependencies into this crate, while avoiding those is part of the reason to have it in the first place.
  • 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)
  • Debug representation is never empty (C-DEBUG-NONEMPTY)
• 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)
  • Crate and its dependencies have a permissive license (C-PERMISSIVE)

[Lokathor]

There's only two unchecked boxes:

• We can't have private fields, that's explicitly against the point of this crate.
• We don't have any public dependencies.

So those boxes should be checked, and then this issue closed? Or did i miss something else?

[madsmtm]

Heh, I've been working on this issue for the past hour, that's why there's only two missing. But I guess I'll just post my thoughts here, and be done with it.

Re private fields:
It might actually make sense for e.g. the error enum, e.g. add a pub struct NotSupported(());, and then require that in HandleError::NotSupported(NotSupported::default()), in case we wanted the ability to add more information later.

But I suppose that the error type is #[non_exhaustive], so we could add more information that way, and besides, we should rather do #143 if we're concerned about extensibility in the error type.

Re public deps:
This was being considered in #134, so I wanted to ensure that we didn't release v1.0 before the dependency did that; but then I read it again, and realised that @notgull already considered that, so I don't think I need to worry about it.