Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Merged by Bors] - Bevy app docs #3539

Closed
wants to merge 17 commits into from
Closed

[Merged by Bors] - Bevy app docs #3539

wants to merge 17 commits into from

Conversation

dbearden
Copy link
Contributor

@dbearden dbearden commented Jan 3, 2022

Objective

Achieve 100% documentation coverage for bevy_app crate.
See #3492

Solution

  • Add #![warn(missing_docs)] to crate root
  • Add doc comments to public items
  • Add doc comment to bevy_utils::define_label macro trait

@dbearden
Add doc comment to define_label macro trait
5854c35
@dbearden
Complete documentation of bevy_app crate
2fe3c1e 
Achieves 100% doc coverage for public items in the bevy_app crate.
Also, fixes a couple of minor typos in other crates.
@dbearden
Add warn(missing_docs)
5868c64
@github-actions github-actions bot added the S-Needs-Triage This issue needs to be labelled label Jan 3, 2022
@alice-i-cecile alice-i-cecile added C-Docs An addition or correction to our documentation A-App Bevy apps and plugins and removed S-Needs-Triage This issue needs to be labelled labels Jan 3, 2022
@alice-i-cecile alice-i-cecile mentioned this pull request Jan 3, 2022
Open
45 tasks
inodentry
inodentry suggested changes Jan 4, 2022
View reviewed changes
Copy link
Contributor

@inodentry inodentry left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your current docs seem a little out-of-place IMO, in that they explain things that aren't directly relevant to understanding App, and don't explain things that are.

I've left you some constructive criticism with suggestions for what to document instead. :)

Also, it is a convention to have the first line of a doc comment be a brief statement of what the thing is, and then have any additional explanation on following lines. Rustdoc will display the first line as the description in brief listings, like search results. You don't want to clutter it with too much text.

crates/bevy_app/src/app.rs Outdated Show resolved Hide resolved
crates/bevy_app/src/app.rs Outdated Show resolved Hide resolved
alice-i-cecile
alice-i-cecile requested changes Jan 5, 2022
View reviewed changes
Copy link
Member

@alice-i-cecile alice-i-cecile left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A few more typos and thoughts. The framing of how we introduce App is particularly critical for the new user experience, so we should spend more time trying to really nail the explanation than might be justified otherwise. The existing docs are fine, but these should be excellent.

crates/bevy_app/src/app.rs Outdated Show resolved Hide resolved
killercup
killercup approved these changes Jan 6, 2022
View reviewed changes
Copy link
Contributor

@killercup killercup left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, left some comments on unimportant details :)

crates/bevy_app/src/app.rs Outdated Show resolved Hide resolved
crates/bevy_app/src/app.rs Outdated Show resolved Hide resolved
crates/bevy_app/src/app.rs Outdated Show resolved Hide resolved
dbearden and others added 3 commits January 6, 2022 09:21
@alice-i-cecile
Copy link
Member

bors r+

bors bot pushed a commit that referenced this pull request Jan 6, 2022
@dbearden
Bevy app docs (#3539)
eca3076 
# Objective

Achieve 100% documentation coverage for bevy_app crate.
See #3492 

## Solution

- Add #![warn(missing_docs)] to crate root
- Add doc comments to public items
- Add doc comment to bevy_utils::define_label macro trait
@bors
Copy link
Contributor

bors bot commented Jan 6, 2022

🔒 Permission denied

Existing reviewers: click here to make dbearden a reviewer

@alice-i-cecile
Copy link
Member

@dbearden That permission is for Cart, Francois and myself :) We just need to wait for the bors bot to do its magic (verify that the PR works on the latest main, then merge it).

@dbearden
Copy link
Contributor Author

dbearden commented Jan 6, 2022

Oops :p

@alice-i-cecile
Copy link
Member

bors seems stuck. Let's try again...

@alice-i-cecile
Copy link
Member

bors r-

@bors
Copy link
Contributor

bors bot commented Jan 6, 2022

Canceled.

@alice-i-cecile
Copy link
Member

bors r+

bors bot pushed a commit that referenced this pull request Jan 6, 2022
@dbearden
Bevy app docs (#3539)
b673c51 
# Objective

Achieve 100% documentation coverage for bevy_app crate.
See #3492 

## Solution

- Add #![warn(missing_docs)] to crate root
- Add doc comments to public items
- Add doc comment to bevy_utils::define_label macro trait
@bors
Copy link
Contributor

bors bot commented Jan 6, 2022

Pull request successfully merged into main.

Build succeeded:

@bors bors bot changed the title Bevy app docs [Merged by Bors] - Bevy app docs Jan 6, 2022
@bors bors bot closed this Jan 6, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@killercup killercup killercup approved these changes

@alice-i-cecile alice-i-cecile alice-i-cecile approved these changes

@inodentry inodentry Awaiting requested review from inodentry

Assignees
No one assigned
Labels
A-App Bevy apps and plugins C-Docs An addition or correction to our documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@dbearden @alice-i-cecile @killercup @inodentry