Better documentation

[madsmtm]

• Document our goals (see fruity's for inspiration). Done in Document our goals #79
• Document various design choices
  • Especially our use of Deref in objc2-foundation, since it conflicts with most guidelines, see the entry in the API guidelines and the (anti-pattern) entry in "Rust Design Patterns"
  • How objc2::foundation assumes that most things are NSObject instead of just Object, since that is what the rest of Cocoa does anyway
• Clean up lib.rs vs. README.md (see README guidelines rust-lang/api-guidelines#254)
• Give proper attribution (link to the original projects that this is a fork of)
• Make docs.rs configuration -> Maybe some build.rs configuration needed for objc-sys. Done in Fix docs.rs setup #89 and Set docs.rs targets on all crates #160
• Add doc(cfg) attributes to document platform-specific APIs? Done in Use doc_auto_cfg on docs.rs #195
• Use unstable documentation features where relevant. Only relevant was notable_traits, and I didn't really find that very useful.
• Link to related projects Grab ideas from, and link to related projects #26
• Maybe add a rustbook with a helpful introduction on how to use the libraries?
  • I'll be adding a tutorial, see Add a tutorial to icrate #494
• Look through rustdoc documentation and get tips from that.
• Clean up changelogs, see Add and/or update changelogs #75
• Add #![warn(rustdoc::missing_doc_code_examples)]?
• Make it clearer which invariants are safety invariants and which are validity invariants (see this for distinction)
• More introduction-level docs for people new to Objective-C / arriving from objc
• Clean up error messages according to https://doc.rust-lang.org/nightly/std/error/index.html#common-message-styles
• Great example of using diataxis:
  • https://docs.rs/winnow
  • https://docs.rs/clap
• The docs in Firefox' developer guide do a pretty good job at a high-level overview of Objective-C
• Lots more!

Also a few missing from the API Guide checklist:

• 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)

[madsmtm]

Another todo: Use #![warn(clippy::undocumented_unsafe_blocks, clippy::multiple_unsafe_ops_per_block)].