component discovery

[robtfm]

Objective

in rendering we are increasingly moving from resources to components attached to the camera entity. each time we do this, we worry about how people (and editors) will find the components.
find a nice way to identify components that can be attached to entities with specific other components.

Solution

add #[derive(PairsWithOthers)] to a component to specify it as a component that likes other things added alongside it. this generates a PairsWithXXX trait that can be linked from the docs for the component. see e.g. Camera3dBundle:

add #[pairs_with(YYY)] to components that want to be on an entity with XXX. this generates an impl of the trait. then the components can be found on the doc page:

• todo: maybe find a better way to reference the PairsWithXXX trait - currently this uses a string lookup in pairs.rs which would need to be updated for each new PairsWithOthers type. Might not be too bad as there are not many of them.
• todo: add pairs_with for many other components (suggestions pls).
• note: this could be a basis for editor functionality as well maybe.

[alice-i-cecile]

This is related to archetype invariants (#1481, #5121). We should think about how this fits into that cohesively.

[james7132]

I can see this being useful in the future, but codegen for the sake of docs seems backwards. Wonder if this could (for now) just generate a #[docs(...) attribute instead and have it forward compatible to generate metadata/code when we have a concrete reason to do so.

[robtfm]

Wonder if this could (for now) just generate a #[docs(...) attribute

do you mean generate a doc attribute on the camera (for example) from the other components?

i did try to #[cfg(doc)] various parts of it to keep codegen down but it seems like when generating docs for a crate, the non-doc-cfg version of imported crates are used as the context for generating docs so that doesn't seem to work.

[alice-i-cecile]

do you mean generate a doc attribute on the camera (for example) from the other components?

Yeah, that's what I would want. If needed we can probably get an appropriate attribute added upstream too.

[robtfm]

sorry but i've got absolutely no idea how i could do that.

[alice-i-cecile]

Yeah; I'll ask around for solutions here. Going to close this out, but I'm chewing on this problem.