-
-
Notifications
You must be signed in to change notification settings - Fork 3.5k
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.
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
bevy_reflect: Improve List::push
and List::pop
docs
#6866
Comments
I clarified the meaning of first/front element and last/back element with some emphasis. What do you think, should I make a PR? Suggestions? /// An ordered, mutable list of [Reflect] items. This corresponds to types like [`std::vec::Vec`].
///
/// This is a sub-trait of [`Array`] as it implements a [`push`](List::push) function, allowing
/// it's internal size to grow.
///
/// This trait expects index 0 to contain the _first_ or _front_ element.
/// The _last_ or _back_ element refers to the element with the largest index.
pub trait List: Reflect + Array {
/// Appends an element to the _back_ of the list.
fn push(&mut self, value: Box<dyn Reflect>);
/// Removes the _last_ element from the list and returns it, or [`None`] if it is empty.
fn pop(&mut self) -> Option<Box<dyn Reflect>>;
/// Clones the list, producing a [`DynamicList`].
fn clone_dynamic(&self) -> DynamicList {
DynamicList {
name: self.type_name().to_string(),
values: self.iter().map(|value| value.clone_value()).collect(),
}
}
} |
Yeah I think that's pretty good. I think I like your choice in extracting that info into the docs for My only other comments are:
If you can, I’d definitely make a PR so we can get more feedback from the community and iterate based off that! |
By the way, how do I create backlinks? 🤔 |
Don't mind personally, but |
# Objective Fixes bevyengine#6866. ## Solution Docs now should describe what the _front_, _first_, _back_, and _last_ elements are for an implementor of the `bevy::reflect::list::List` Trait. Further, the docs should describe how `bevy::reflect::list::List::push` and `bevy::reflect::list::List::pop` should act on these elements. Co-authored-by: Linus Käll <linus.kall.business@gmail.com>
# Objective Fixes bevyengine#6866. ## Solution Docs now should describe what the _front_, _first_, _back_, and _last_ elements are for an implementor of the `bevy::reflect::list::List` Trait. Further, the docs should describe how `bevy::reflect::list::List::push` and `bevy::reflect::list::List::pop` should act on these elements. Co-authored-by: Linus Käll <linus.kall.business@gmail.com>
How can Bevy's documentation be improved?
The docs on
List::push
andList::pop
should better explain the directionality of those operations, as explained in this comment.We should direct manual (and internal) implementors to uphold the contract that:
The docs already do this to an extent, but they could give just a bit more detail and make the guarantee more explicit so implementors don't miss it!
The text was updated successfully, but these errors were encountered: