[Merged by Bors] - Update `mouse.rs` docs in `bevy_input` #4518

ghost · 2022-04-18T14:45:16Z

Objective

Part of the splitting process of docs: Documentation and clean up of bevy_input #3692.

Solution

Document mouse.rs inside of bevy_input.

nicopap

Finally some doc! 👍

Though there are some awkward bits that I think could be left out.

nicopap · 2022-04-25T17:30:44Z

crates/bevy_input/src/mouse.rs

+/// resource. The resource stores the data of the buttons of a mouse and can be accessed
+/// inside of a system.


I don't understand this bit: "The resource stores the data of the buttons of a mouse"

Suggested change

/// resource. The resource stores the data of the buttons of a mouse and can be accessed

/// inside of a system.

/// resource. It can be accessed inside of a system with a `Res<Input<MouseButton>>`

/// parameter.

(Second half is just a suggestion. It's only the "data of a button" that I think should be really fixed)

crates/bevy_input/src/mouse.rs

nicopap · 2022-04-25T17:36:30Z

crates/bevy_input/src/mouse.rs

+///
+/// This event is the translated version of the `WindowEvent::MouseWheel` from the `winit` crate.
+/// It is available to the end user and can be used for game logic.


Suggested change

///

/// This event is the translated version of the `WindowEvent::MouseWheel` from the `winit` crate.

/// It is available to the end user and can be used for game logic.

nicopap · 2022-04-25T17:37:07Z

crates/bevy_input/src/mouse.rs

+///
+/// This event is the translated version of the `DeviceEvent::MouseMotion` from the `winit` crate.
+/// It is available to the end user and can be used for game logic.


Suggested change

///

/// This event is the translated version of the `DeviceEvent::MouseMotion` from the `winit` crate.

/// It is available to the end user and can be used for game logic.

nicopap · 2022-04-25T17:38:31Z

crates/bevy_input/src/mouse.rs

+///
+/// This event is the translated version of the `WindowEvent::MouseInput` from the `winit` crate.
+/// It is available to the end user and can be used for game logic.


Suggested change

///

/// This event is the translated version of the `WindowEvent::MouseInput` from the `winit` crate.

/// It is available to the end user and can be used for game logic.

Is it relevant to the end user to say "this comes from the winit crate"? I don't feel like so.

Regardless, I think "It is available to the end user and can be used for game logic." doesn't add much value and should be removed.

crates/bevy_input/src/mouse.rs

Co-authored-by: Troels Jessen <kairyuka@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>

ghost · 2022-04-25T18:12:55Z

I don't understand this bit: "The resource stores the data of the buttons of a mouse"

@nicopap I can see how it could be confusing. Do you like "The resource stores the state of the mouse buttons" more?

Is it relevant to the end user to say "this comes from the winit crate"? I don't feel like so. Regardless, I think "It is available to the end user and can be used for game logic." doesn't add much value and should be removed.

I wouldn't say so. The winit information might be a little much, but I think it doesn't hurt to leave it in there. The sentence that it is available to the end user and that it can be used for game logic seems like an important notice if you are just skimming through the input docs.

The addition of the actual resource type you would have to use (Res<Input<MouseButton>>) was something I had inside of there. I removed it, because @alice-i-cecile noticed that it is too much and I definitely agree with that. It just adds a lot of boilerplate.

nicopap · 2022-04-25T19:59:43Z

I think the winit line is fine. It's actually quite useful for the user. If they already know winit, they know they can re-use their knowledge in bevy thanks to that doc line. And if they don't know winit, but need more in depth understanding of bevy's internal, it's great that they have some hint of where to go. I've reconsidered my position.

I mean that "It is available to the end user" is a bit redundant on a doc string. As a user, I don't really need to know that a type is available to me in a documentation page. If I am reading the documentation for that type, it means that necessarily it is available to me, so no need to tell it. Maybe just keeping "this can be used in game logic"?

"Store the data of a button" is a bit of an awkward sentence. And all things considered, doesn't add much that is not already said, I find the doc is improved with the sentence removed.

crates/bevy_input/src/mouse.rs

alice-i-cecile · 2022-04-25T20:49:35Z

Happy to merge this once @nicopap approves :)

nicopap · 2022-04-26T05:47:04Z

Ah, this github ui confuses me. It's all good for me now

alice-i-cecile · 2022-04-26T05:58:40Z

bors r+

# Objective - Part of the splitting process of #3692. ## Solution - Document `mouse.rs` inside of `bevy_input`. Co-authored-by: KDecay <KDecayMusic@protonmail.com>

bors · 2022-04-26T07:03:27Z

Timed out.

mockersf · 2022-04-26T17:32:37Z

bors r+

# Objective - Part of the splitting process of #3692. ## Solution - Document `mouse.rs` inside of `bevy_input`. Co-authored-by: KDecay <KDecayMusic@protonmail.com>

bors · 2022-04-26T17:55:00Z

Pull request successfully merged into main.

Build succeeded:

# Objective - Part of the splitting process of bevyengine#3692. ## Solution - Document `mouse.rs` inside of `bevy_input`. Co-authored-by: KDecay <KDecayMusic@protonmail.com>

Update mouse.rs docs

3ed149c

github-actions bot added the S-Needs-Triage This issue needs to be labelled label Apr 18, 2022

ghost added C-Docs An addition or correction to our documentation A-Input Player input via keyboard, mouse, gamepad, and more and removed S-Needs-Triage This issue needs to be labelled labels Apr 18, 2022

alice-i-cecile approved these changes Apr 18, 2022

View reviewed changes

ghost changed the title ~~Update mouse.rs docs~~ Update mouse.rs docs in bevy_input Apr 18, 2022

nicopap suggested changes Apr 25, 2022

View reviewed changes

Sheepyhead suggested changes Apr 25, 2022

View reviewed changes

crates/bevy_input/src/mouse.rs Outdated Show resolved Hide resolved

crates/bevy_input/src/mouse.rs Outdated Show resolved Hide resolved

KDecay and others added 2 commits April 25, 2022 19:59

Small nits

321f230

Co-authored-by: Troels Jessen <kairyuka@gmail.com> Co-authored-by: Nicola Papale <nicopap@users.noreply.github.com>

Merge branch 'main' into update_mouse_docs

6fb060c

Sheepyhead approved these changes Apr 25, 2022

View reviewed changes

Remove sentence and rephrasing

28f3d07

alice-i-cecile reviewed Apr 25, 2022

View reviewed changes

crates/bevy_input/src/mouse.rs Outdated Show resolved Hide resolved

alice-i-cecile reviewed Apr 25, 2022

View reviewed changes

crates/bevy_input/src/mouse.rs Outdated Show resolved Hide resolved

Remove even more sentences

a31256b

nicopap approved these changes Apr 26, 2022

View reviewed changes

bors bot pushed a commit that referenced this pull request Apr 26, 2022

Update mouse.rs docs in bevy_input (#4518)

14da629

# Objective - Part of the splitting process of #3692. ## Solution - Document `mouse.rs` inside of `bevy_input`. Co-authored-by: KDecay <KDecayMusic@protonmail.com>

mockersf approved these changes Apr 26, 2022

View reviewed changes

mockersf added the S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it label Apr 26, 2022

bors bot pushed a commit that referenced this pull request Apr 26, 2022

Update mouse.rs docs in bevy_input (#4518)

50a1470

# Objective - Part of the splitting process of #3692. ## Solution - Document `mouse.rs` inside of `bevy_input`. Co-authored-by: KDecay <KDecayMusic@protonmail.com>

bors bot changed the title ~~Update mouse.rs docs in bevy_input~~ [Merged by Bors] - Update mouse.rs docs in bevy_input Apr 26, 2022

bors bot closed this Apr 26, 2022

ghost deleted the update_mouse_docs branch August 7, 2022 08:27

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[Merged by Bors] - Update `mouse.rs` docs in `bevy_input` #4518

[Merged by Bors] - Update `mouse.rs` docs in `bevy_input` #4518

ghost commented Apr 18, 2022

nicopap left a comment

nicopap Apr 25, 2022

nicopap Apr 25, 2022

nicopap Apr 25, 2022

nicopap Apr 25, 2022

ghost commented Apr 25, 2022

nicopap commented Apr 25, 2022

alice-i-cecile commented Apr 25, 2022

nicopap commented Apr 26, 2022

alice-i-cecile commented Apr 26, 2022

bors bot commented Apr 26, 2022

mockersf commented Apr 26, 2022

bors bot commented Apr 26, 2022

		/// resource. The resource stores the data of the buttons of a mouse and can be accessed
		/// inside of a system.

	///
	/// This event is the translated version of the `WindowEvent::MouseWheel` from the `winit` crate.
	/// It is available to the end user and can be used for game logic.

[Merged by Bors] - Update mouse.rs docs in bevy_input #4518

[Merged by Bors] - Update mouse.rs docs in bevy_input #4518

Conversation

ghost commented Apr 18, 2022

Objective

Solution

nicopap left a comment

Choose a reason for hiding this comment

nicopap Apr 25, 2022

Choose a reason for hiding this comment

nicopap Apr 25, 2022

Choose a reason for hiding this comment

nicopap Apr 25, 2022

Choose a reason for hiding this comment

nicopap Apr 25, 2022

Choose a reason for hiding this comment

ghost commented Apr 25, 2022

nicopap commented Apr 25, 2022

alice-i-cecile commented Apr 25, 2022

nicopap commented Apr 26, 2022

alice-i-cecile commented Apr 26, 2022

bors bot commented Apr 26, 2022

mockersf commented Apr 26, 2022

bors bot commented Apr 26, 2022

[Merged by Bors] - Update `mouse.rs` docs in `bevy_input` #4518

[Merged by Bors] - Update `mouse.rs` docs in `bevy_input` #4518