Add docs to all top level items

[davidpdrsn]

This adds high level docs to all top level items. The most relevant sections are on the root module and #[derive(Reflect)].

Part of https://github.com/EmbarkStudios/mirror-mirror/issues/4

[davidpdrsn]

does each reflect call allocate?

For the Reflect trait it depends on which method you call:

• as_reflect doesn't allocate, it just returns self so rust can cast the dyn type. Same for reflect_ref, reflect_mut, etc.
• to_value will not allocate for scalar types (except String) but will allocate for structs, enums, etc.

FromReflect is similar where it wont allocate for scalars but will for other types.

Methods like Struct::field, Enum::field, etc don't allocate. The one exception is <BTreeMap as Map> where get and get_mut call FromReflect and thus might allocate. I don't think we can fix this since get and get_mut must take key: &dyn Reflect to be object safe, so we can't use generics.

Additionally most things have fields and fields_mut methods to iterate over the fields. Here fields wont allocate but fields_mut will. This is due to a limitation in the borrow checker that requires GATs and LendingIterator to fix. Note that bevy_reflect doesn't even have fields_mut methods, probably for this reason. I have found the mutable version very useful so I think its worth the tradeoff.

or is there a single lazy allocation of the type descriptor that's kept for the entire lifetime of a value? or is the type descriptor const-created somehow?

Currently when you call Reflect::type_info (alias for Typed::type_info) it'll allocate a new TypeRoot every time. Thats not great and is something that'd be good to fix. I don't think it'll require breaking changes to fix.

I wish it could be const but I don't think thats possible due to how the graph is built.