[Merged by Bors] - Clarify the behaviour of iter_many in the docs
#5973
Conversation
james7132
added
C-Docs
| /// This can only return immutable data (mutable data will be cast to an immutable form). | ||
| /// See [`Self::iter_many_mut`] for queries that contain at least one mutable component. | ||
| /// Items are returned in the order of the list of entities. | ||
| /// Entities that don't match the query are skipped. |
There was a problem hiding this comment.
What about linking to QueryManyIter instead of duplicating text? That would remove the risk of divergent evolution.
There was a problem hiding this comment.
I agree, but didn't we discuss/do the opposite in #4989?
There was a problem hiding this comment.
I really think not. I always try my best to keep API docs in their place and avoid duplicating them.
There was a problem hiding this comment.
My bad, I misremembered how that conversation went down. I still wish we could stick to a single convention with regard to whether the meat of the docs live on the iterator type or the method, but as long as everything's linked up it's not worth fussing about.
There was a problem hiding this comment.
The rule of thumb is to document as close as possible to the implementation, so the iterator. The problem may be that the closest item is not very visible. In this case, good linking practices help a lot.
|
Chiming in briefly to say that this is information I really wanted when I was browsing these docs recently. Will look a bit closer later. |
james7132
added
the
S-Ready-For-Final-Review
|
bors r+ |
Add the following message: ``` Items are returned in the order of the list of entities. Entities that don't match the query are skipped. ``` Additionally, the docs in `iter.rs` and `state.rs` were updated to match those in `query.rs`. Co-authored-by: devil-ira <justthecooldude@gmail.com>
bors
bot
changed the title
iter_many in the docsiter_many in the docs
Add the following message: ``` Items are returned in the order of the list of entities. Entities that don't match the query are skipped. ``` Additionally, the docs in `iter.rs` and `state.rs` were updated to match those in `query.rs`. Co-authored-by: devil-ira <justthecooldude@gmail.com>
Add the following message: ``` Items are returned in the order of the list of entities. Entities that don't match the query are skipped. ``` Additionally, the docs in `iter.rs` and `state.rs` were updated to match those in `query.rs`. Co-authored-by: devil-ira <justthecooldude@gmail.com>
Add the following message: ``` Items are returned in the order of the list of entities. Entities that don't match the query are skipped. ``` Additionally, the docs in `iter.rs` and `state.rs` were updated to match those in `query.rs`. Co-authored-by: devil-ira <justthecooldude@gmail.com>
Add the following message:
Additionally, the docs in
iter.rsandstate.rswere updated to match those inquery.rs.