Added documentation for ParamSet.

[Nanox19435]

Objective

Fixes #4729.
Adds documentation for ParamSet and an example of its usage.

[Nilirad]

Congratulations on your first PR here! Documenting ParamSet is immensely useful.

I added my comments below about some details that can be improved. On the general side, I would advise you to follow some of the tips in #4754, especially breaking lines at sentence level.

[alice-i-cecile]

Thanks for the contribution, this is a marked improvement over nothing and the technical side of the explanation is spot-on.

@Nilirad's comments are excellent; try your best to address those. Other than that, there are a couple of formatting nits.

1. Use spaces after comments.
2. Try to split your doc comments at the sentence level so they're cleaner in version control.

[Nanox19435]

Thanks for the feedback everyone, and apologies for the delay in implementing it. I hope this is good enough!

[alice-i-cecile]

Not a problem! Could you press "Resolve comment" on the feedback you've addressed so this is easier to review?

[alice-i-cecile]

Looking much better! A couple small changes; this is ready to go once those suggestions are accepted :)

[Nilirad]

I would like to address some possible high level improvements that can be made:

• The panicking example should not be in the “Panics” section, since it's not the ParamSet that is panicking. It can be moved under the “Example” section, before the good example. Also, a little bit of text before and after the bad example to connect the two does not hurt.
• As you can see by rendering the docs, some comments in the examples are too long, and you need to scroll horizontally to read it. This is unconvenient. You can fix that for the majority of screens by manually wrapping the comments before the 100th column (still make sure to render the docs to check for it).
• I would move the introductory text that you include as comments at the beginning of the code block. Putting it just before the code block increases readability and focuses the reader's attention to the code, since it's no longer cluttered by long comments.

---

Tip: I don't know if you can do it, but you can render the docs to check how they looks with the command:

cargo doc -p bevy_ecs --no-deps --open

This will open the docs in your browser. Then you can search for ParamSet to see the docs you made 😄

[Nanox19435]

I think It should be done for now. Thanks for all the tips and for reviewing!

[alice-i-cecile]

Suggested change

	/// // An entity may have both the Enemy and Ally components, causing two mutable references to the same Health component to be active at once.
	/// // An entity may have both the Enemy and Ally components, causing two mutable references to the same Health component to be active at once.
	/// // ParamSet lets you avoid this by only handing out mutable references to one conflicting query at a time.

[alice-i-cecile]

This looks good now! Personally I would structure the example as:

# Example

[EXPLANATION OF MUTUALLY INCOMPATIBLE DATA]

[FAILING SYSTEM BLOCK]

[EXPLANATION OF HOW PARAMSET ONLY HANDS OUT ONE PIECE OF DATA AT A TIME]

[FIXED CODE USING A PARAMSET]

But this is really just a matter of taste, so I'll leave this call to you.

[Nilirad]

I personally think that the failing example should stay in the “Example” section, since the “Panic” section is misleading because ParamSet does not panic. I particularly like the way @alice-i-cecile laid out the example, to guide the progression from a wrong usage of system parameters to a correct one using ParamSet.

[CGMossa]

Maybe this is a bit of a stretch, but I would like an example added here that uses a system-param that isn't Query, and perhaps an example with ParamSet<(EventReader<Spawn>, EventWriter<Spawn>)> where Spawn is some event..
Reason for this is that this sort of encapsulates the issue in one thing..

[JoJoJet]

@Nanox19435 hey, do you plan on finishing this PR? If not, we can put it up for adoption and let someone else take care of it :)

[JoJoJet]

Closing in favor of #6998. You'll still get credit in the new PR, of course.