move bsn!/bsn_list! macro docs to bevy_scene crate re-export location to enable doc-links

[laundmo]

Problem

Currently, the bsn! macro is documented twice: as bevy_scene module docs and on bev_scene_macros::bsn itself. This means docs need to be updated in 2 locations, and has potential to cause confusion.

The intention of

• Add docs for bsn! macro #24047

seems to mostly have been for IDE hover docs, which sadly do not work with this proposal, but more on that (including a workaround till fixed) later.

Proposal

Rustdoc allows a slightly tricky way of moving docs to the re-export position, instead of the definition, by combingin #[doc(hidden)] with #[doc(inline)]

Example:
bevy_scene/macros/src/lib.rs:

/// Some docs on original item here
#[doc(hidden)]
#[proc_macro]
pub fn bsn(input: TokenStream) -> TokenStream {
    crate::bsn_impl::bsn(input)
}

bevy_scene/src/lib.rs

/// Docs for the bsn macro
///
#[doc(inline)]
pub use bevy_scene_macros::bsn;

This renders as:

with the proc-macro crate docs not being generated as separate entries.

The rust-analyzer issue

Sadly, rust-analyzer currently does not respect #[doc(hidden)] and #[doc(inline)] at all. It always shows the docs for the original item.
Relevant issues:

• Proper support for import aliases and attributes on imports rust-lang/rust-analyzer#14079
• rust-analyzer doesn't handle docs on exported proc-macros properly rust-lang/rust-analyzer#13431

Therefore, i propose the following until rust-analyzer respects #[doc(hidden)] and #[doc(inline)]:

Move the current bsn macro docs into bevy_scene to benefit from intra-doc linking. At the end of these inline docs, put a section starting with something like Brief overview for rust-analyzer hover docs:. Due to inline docs being preprended (see the example above) before item docs, this allows a shorter block of docs shown by IDEs on hover to exist on the macro itself. This should start with a full url link to the bsn! macro docs, and only explain a few very basics or perhaps only show a concise macro syntax example. That much will still be helpful to those who just need a quick reminder, while directing anyone who wants to understand more to the properly linked docs.

I think for a workaround thats solid enough without loosing intra-doc links and doctests as we currently are. Plus, having the docs in bevy_scene makes it less likely they'll desync with the bevy_scene module docs over time.