Split Component::register_component_hooks into individual methods

[bushrat011899]

Objective

• Fixes Refactor Component::init_component_hooks to split apart component hook methods #17411

Solution

• Deprecated Component::register_component_hooks
• Added individual methods for each hook which return None if the hook is unused.

Testing

• CI

---

Migration Guide

Component::register_component_hooks is now deprecated and will be removed in a future release. When implementing Component manually, also implement the respective hook methods on Component.

// Before
impl Component for Foo {
    // snip
    fn register_component_hooks(hooks: &mut ComponentHooks) {
            hooks.on_add(foo_on_add);
    }
}

// After
impl Component for Foo {
    // snip
    fn on_add() -> Option<ComponentHook> {
            Some(foo_on_add)
    }
}

Notes

I've chosen to deprecate Component::register_component_hooks rather than outright remove it to ease the migration guide. While it is in a state of deprecation, it must be used by Components::register_component_internal to ensure users who haven't migrated to the new hook definition scheme aren't left behind. For users of the new scheme, a default implementation of Component::register_component_hooks is provided which forwards the new individual hook implementations.

Personally, I think this is a cleaner API to work with, and would allow the documentation for hooks to exist on the respective Component methods (e.g., documentation for OnAdd can exist on Component::on_add). Ideally, Component::on_add would be the hook itself rather than a getter for the hook, but it is the only way to early-out for a no-op hook, which is important for performance.

Migration Guide

Component::register_component_hooks has been deprecated. If you are manually implementing the Component trait and registering hooks there, use the individual methods such as on_add instead for increased clarity.

[james-j-obrien]

Needs minor doc changes to pass CI, but I like this API and think the changes generally look good.

[ElliottjPierce]

Looks good to me! Definitely need another opinion on the proc macro code. I'm no expert there.

Only downside here is that it may add more complexity to add more kinds of hooks, but I don't see that happening very often, and I think it's worth it for the readability. IDK why it wasn't designed like this in the first place.

[ElliottjPierce]

IDK, but could you do Path::to_token_stream here instead of passing a closure? I'm no expert here, but if that's possible, it might make it a bit more readable. There's a few other places here too that could use that if it's possible.