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] - Hide docs for concrete impls of Fetch, FetchState, and SystemParamState #4250

Closed
wants to merge 11 commits into from
Closed

[Merged by Bors] - Hide docs for concrete impls of Fetch, FetchState, and SystemParamState #4250

wants to merge 11 commits into from

Conversation

james7132
Copy link
Member

@james7132 james7132 commented Mar 18, 2022 •
edited
Loading

Objective

The following pages in the docs are rather noisy, and the types they point to are not particularly useful by themselves:

Solution

  • Replace docs on these types with #[doc(hidden)].
  • Hide InputMarker too.

@github-actions github-actions bot added the S-Needs-Triage This issue needs to be labelled label Mar 18, 2022
@james7132 james7132 added C-Docs An addition or correction to our documentation A-ECS Entities, components, systems, and events and removed S-Needs-Triage This issue needs to be labelled labels Mar 18, 2022
@mockersf
Copy link
Member

would the #[doc(hidden)] hides them from the https://dev-docs.bevyengine.org/bevy/ecs/query/trait.ReadOnlyFetch.html#implementors page?

While this page is not very... friendly, it's still useful to list all the struct that implement that trait.

@james7132
Copy link
Member Author

would the #[doc(hidden)] hides them from the https://dev-docs.bevyengine.org/bevy/ecs/query/trait.ReadOnlyFetch.html#implementors page?

While this page is not very... friendly, it's still useful to list all the struct that implement that trait.

It seems like it would, but the supported WorldQuery implementors are still there, which is what end users will end up interacting with anyway. The exact implementors for Fetch, ReadOnlyFetch, and FetchState are, IMO, largely an implementation detail that really doesn't need to be publicly documented.

@james7132 james7132 mentioned this pull request Mar 19, 2022
Closed
alice-i-cecile
alice-i-cecile requested changes Mar 19, 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.

I like hiding these, but I would prefer to leave the doc comments in place. They're useful guidance for developers ("what the heck is this?"), and there's no cost to keeping them.

ghost
ghost approved these changes Mar 21, 2022
View reviewed changes
Copy link

@ghost ghost left a comment

Choose a reason for hiding this comment

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

I like this change. Nothing got hidden that end users are interacting with and the docs will be a lot less noisy this way. I was quite impressed how noisy the docs look currently.

@james7132 james7132 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 Mar 21, 2022
@alice-i-cecile
Copy link
Member

bors r+

bors bot pushed a commit that referenced this pull request Mar 21, 2022
@james7132
Hide docs for concrete impls of Fetch, FetchState, and SystemParamSta…
86907f1 
…te (#4250)

# Objective
 The following pages in the docs are rather noisy, and the types they point to are not particularly useful by themselves:

 - http://dev-docs.bevyengine.org/bevy/ecs/query/index.html
 - http://dev-docs.bevyengine.org/bevy/ecs/system/index.html

## Solution
 
- Replace docs on these types with `#[doc(hidden)]`.
- Hide `InputMarker`  too.
@bors
Copy link
Contributor

bors bot commented Mar 21, 2022

Build failed:

@ghost
Copy link

ghost commented Mar 21, 2022

Looks like https://wiki.ubuntu.com/WSL is down. CI is also failing on #4275 and I also can't access the site.

@james7132
Copy link
Member Author

bors retry

bors bot pushed a commit that referenced this pull request Mar 21, 2022
@james7132
Hide docs for concrete impls of Fetch, FetchState, and SystemParamSta…
4c1678c 
…te (#4250)

# Objective
 The following pages in the docs are rather noisy, and the types they point to are not particularly useful by themselves:

 - http://dev-docs.bevyengine.org/bevy/ecs/query/index.html
 - http://dev-docs.bevyengine.org/bevy/ecs/system/index.html

## Solution
 
- Replace docs on these types with `#[doc(hidden)]`.
- Hide `InputMarker`  too.
@bors
Copy link
Contributor

bors bot commented Mar 21, 2022

Pull request successfully merged into main.

Build succeeded:

@bors bors bot changed the title Hide docs for concrete impls of Fetch, FetchState, and SystemParamState [Merged by Bors] - Hide docs for concrete impls of Fetch, FetchState, and SystemParamState Mar 21, 2022
@bors bors bot closed this Mar 21, 2022
aevyrie pushed a commit to aevyrie/bevy that referenced this pull request Jun 7, 2022
@james7132 @aevyrie
Hide docs for concrete impls of Fetch, FetchState, and SystemParamSta…
03020bf 
…te (bevyengine#4250)

# Objective
 The following pages in the docs are rather noisy, and the types they point to are not particularly useful by themselves:

 - http://dev-docs.bevyengine.org/bevy/ecs/query/index.html
 - http://dev-docs.bevyengine.org/bevy/ecs/system/index.html

## Solution
 
- Replace docs on these types with `#[doc(hidden)]`.
- Hide `InputMarker`  too.
@james7132 james7132 deleted the hide-docs branch June 22, 2022 08:24
ItsDoot pushed a commit to ItsDoot/bevy that referenced this pull request Feb 1, 2023
@james7132 @ItsDoot
Hide docs for concrete impls of Fetch, FetchState, and SystemParamSta…
7ee7f01 
…te (bevyengine#4250)

# Objective
 The following pages in the docs are rather noisy, and the types they point to are not particularly useful by themselves:

 - http://dev-docs.bevyengine.org/bevy/ecs/query/index.html
 - http://dev-docs.bevyengine.org/bevy/ecs/system/index.html

## Solution
 
- Replace docs on these types with `#[doc(hidden)]`.
- Hide `InputMarker`  too.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

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

Assignees
No one assigned
Labels
A-ECS Entities, components, systems, and events C-Docs An addition or correction to our documentation S-Ready-For-Final-Review This PR has been approved by the community. It's ready for a maintainer to consider merging it
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@james7132 @mockersf @alice-i-cecile