Function signature of `resource_equals` differs from implementation in docs

[JasmineLowen]

How can Bevy's documentation be improved?

In the latest version of bevys docs, the signature of resource_equals seems to be buggy.

I was looking into how the common run conditions were implemented and was a bit confused when I saw this

I needed to check the bevy repos code to verify that the returned closure returns a bool.

I don't know how to fix it yet though, but I'll see what I can do!

[Selene-Amanita]

To note: it has the correct signature in the sub-crate's documentation: https://docs.rs/bevy_ecs/latest/bevy_ecs/schedule/common_conditions/fn.resource_equals.html

And it also happens on main, and for other conditions in the common_conditions module.

any_with_components appears with a weird unnecessary line break in bevy_ecs: https://docs.rs/bevy_ecs/latest/bevy_ecs/schedule/common_conditions/fn.any_with_component.html but not in bevy: https://docs.rs/bevy/latest/bevy/ecs/schedule/common_conditions/fn.any_with_component.html , traits are not always at the same place (in where or not), PartialEq to PartialEq<T>, ...

Probably more a problem with rustdoc, but we can maybe get around it.

Edit: Possibly related issue for rustdoc: rust-lang/rust#44306

[fmease]

This is definitely the fault of rustdoc (source: I'm an active rustdoc contributor specializing in cross-crate reexports).

• The trait bound T: … + PartialEq being rendered as T: … + PartialEq<T> is going to be fixed in rustdoc: elide cross-crate default generic arguments rust-lang/rust#112463.
• Not showing -> bool is defo a serious bug and we've had similar ones in the past. Looking into fixing this. Edit: Opened rustdoc's resugaring of projection predicates to type bindings is flawed rust-lang/rust#113015 for now, PR hopefully coming soon
• Theoretically I could also fix Res<T> being rendered as Res<'_, T> but I'm not really fond of this at the moment as I'm an avid fan of explicitly elided lifetimes (the '_ part) and its related lint elided_lifetimes_in_paths part of rust_2018_idioms which flags implicitly elided lifetimes.

[Selene-Amanita]

@fmease thanks a lot for the confirmation! Any idea why there's a line break in any_with_components doc?

[fmease]

Any idea why there's a line break in any_with_components doc?

Ah, that doesn't look ideal. I've just checked and it's because rustdoc measures & and adds up the length of the function name, the arguments and the return type, realizes it's bigger than 80 bytes and thus inserts some line breaks inside the argument list.
I'm sure this heuristic can be improved (made more sophisticated and also made to count the generics) but I think the most straightforward fix would be to just keep it the way it is and to just not print an extra line break if the argument list is empty:

pub fn any_with_component<T: Component>(
) -> impl FnMut(Query<'_, '_, (), With<T>>) -> bool + Clone

^ Would you be fine with this output or would you rather have rustdoc output () (parentheses on the same line)? This would imply increasing the threshold, otherwise we would end up with non-standard style. For comparison, rustfmt also breaks empty argument lists into two lines similar to the example I gave above (except that the threshold seems to be a bit higher).

[Selene-Amanita]

^ Would you be fine with this output or would you rather have rustdoc output ()

I am fine with this output, I'll ask other people on Bevy's discord just in case.

[fmease]

Ah, I've just noticed that this regressed in rust-lang/rust#109011 meaning that before that it used to be rendered just like I proposed.