Better documentation

[madsmtm]

• [x] Document our goals (see fruity's for inspiration). Done in https://github.com/madsmtm/objc2/pull/79
• [ ] Document various design choices
  • [x] 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
• [x] Clean up lib.rs vs. README.md (see https://github.com/rust-lang/api-guidelines/discussions/254)
• [x] Give proper attribution (link to the original projects that this is a fork of)
• [x] Make docs.rs configuration -> Maybe some build.rs configuration needed for objc-sys. Done in https://github.com/madsmtm/objc2/pull/89 and https://github.com/madsmtm/objc2/pull/160
• [x] Add doc(cfg) attributes to document platform-specific APIs? Done in https://github.com/madsmtm/objc2/pull/195
• [x] ~Use unstable documentation features where relevant.~ Only relevant was notable_traits, and I didn't really find that very useful.
• [x] Link to related projects https://github.com/madsmtm/objc/issues/26
• [ ] Maybe add a rustbook with a helpful introduction on how to use the libraries?
  • I'll be adding a tutorial, see https://github.com/madsmtm/objc2/pull/494
• [x] Look through rustdoc documentation and get tips from that.
• [x] Clean up changelogs, see #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
• [x] 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)].