document public items, fix doc tests

[B-Reif]

This PR adds a lint to warn for missing docs, adds some documentation for public items that didn't have any, and fixes examples that were failing in rustdoc tests.

[MrGVSV]

Looks great! This actually came at the perfect time because I'm doing some major rework to the project (transitioning to Bevy's Reflect from the deprecated typetag) and really needed to update the docs for the last patch release of this version. So thank you for this! 😄

Just a few suggestions/changes.

[MrGVSV]

Is it worth suggesting that it's often best used as use bevy_proto::prelude::*? Or is it better to just let the user decide how they want to use it?

[B-Reif]

I think this might depend on how they're using it, and if they're using all of the bevy_proto types in the same place. I'd just let users decide how to use it.

On a related note I was thinking we could reduce the number of public modules. Specifically, we could hide components and plugin and just pub use components::ProtoComponent and pub use plugin::ProtoPlugin since those mods don't contain anything else anyway.

[MrGVSV]

Yeah, let's do that.

[B-Reif]

One downside to our current approach is that the blocks in the README aren't tested by cargo test, so it's possible for them to be incorrect / out of date. I'm not sure what the best approach is to solving that.

[MrGVSV]

One downside to our current approach is that the blocks in the README aren't tested by cargo test, so it's possible for them to be incorrect / out of date. I'm not sure what the best approach is to solving that.

That's true. Maybe we can do something like: rust-lang/cargo#383 (comment) in lib.rs?

[B-Reif]

Sure, I'll give it a go

[B-Reif]

@MrGVSV Two of the doc tests for the README are failing whenever we try to get EntityCommands from ProtoCommands:

error[E0623]: lifetime mismatch
  --> src\lib.rs:397:46
   |
22 |     fn insert_self(&self, proto_commands: &mut ProtoCommands, asset_server: &Res<AssetServer>) {
   |                                                ------------- this type is declared with multiple lifetimes...
23 |         let handle: Handle<Image> = asset_server.load(self.texture_path.as_str());
24 |         let entity_commands = proto_commands.raw_commands();
   |                                              ^^^^^^^^^^^^ ...but data with one lifetime flows into the other here

error: aborting due to previous error

For more information about this error, try `rustc --explain E0623`.
Couldn't compile the test.

I'm not sure how to resolve this. It seems like this error pops up whenever raw_commands is invoked.

[MrGVSV]

@MrGVSV Two of the doc tests for the README are failing whenever we try to get EntityCommands from ProtoCommands:

error[E0623]: lifetime mismatch
  --> src\lib.rs:397:46
   |
22 |     fn insert_self(&self, proto_commands: &mut ProtoCommands, asset_server: &Res<AssetServer>) {
   |                                                ------------- this type is declared with multiple lifetimes...
23 |         let handle: Handle<Image> = asset_server.load(self.texture_path.as_str());
24 |         let entity_commands = proto_commands.raw_commands();
   |                                              ^^^^^^^^^^^^ ...but data with one lifetime flows into the other here

error: aborting due to previous error

For more information about this error, try `rustc --explain E0623`.
Couldn't compile the test.

I'm not sure how to resolve this. It seems like this error pops up whenever raw_commands is invoked.

Hm, I wonder if it's because of the lifetime on EntityCommands here:

bevy_proto/src/data.rs

Lines 341 to 343 in 22c84e3

	pub fn raw_commands(&'p mut self) -> &'p mut EntityCommands<'w, 's, 'a> {
	&mut self.commands
	}

Does eliding the 'p lifetime on the references resolve the issue?

If not, we could maybe try making 'p: 'a? Not sure if that would fix it though...

[B-Reif]

Does eliding the 'p lifetime on the references resolve the issue?

Yes, that did it!

[MrGVSV]

Looks good! Thank you for these changes!