Why are you deleting documentation?

If this was AI-generated, please make sure you can explain every change in the diff.

I've restored the missing documentation for iter_next_chunk and added detailed docs for the new backward-filling logic — sorry, it was a few custom config rules I added in my editor that trimmed them out. I'll make sure it doesn't happen again!

i implemented a new GuardBack specifically to handle the reverse-initialization logic safely. While the standard Guard fills an array from 0..N, GuardBack fills from N down to 0. If a panic occurs, GuardBack::drop correctly identifies and drops only the partial results at the end of the array (the len - initialized..len slice). This is required because we're pulling from the back of the iterator but want the final array to be in the original order.

I followed the same pattern as next_chunk in #98326 & ArrayChunks implementation in #100450.

I'm wondering if we really need a dedicated GuardBack<'a, T> struct for this? The underlying members of GuardBack<'a, T> is the same as Guard<'a, T> with the only difference being the Drop implementation, which makes me think that Guard<'a, T> can be reused for this purpose.

For example, I was taking a look at this discussion on using TypeId, which exists in both core::any and std::any module. Would it be possible (or a good idea) to approach making the guard like so:

// Empty ZST stucts
struct Front {};
struct Back {};

struct Guard<'a, T, D: 'static> {
    /// The array to be initialized.
    pub array_mut: &'a mut [MaybeUninit<T>],
    /// The number of items that have been initialized so far.
    pub initialized: usize,
    _direction: D
}

impl<T, D: 'static> std::ops::Drop for Guard<'_, T, D> {
    fn drop(&mut self) {
        match TypeId::of::<D>() {
            id if id == TypeId::of::<Front>() => {
                // drop impl from Guard<'a, T>
            },
            id if id == TypeId::of::<Back>() => {
                // drop impl from GuardBack<'a, T>
            },
            _ => {
                // this shouldn't happen (mark as unreachable!()?)
            },
        }
    }
}

If we are able to reuse Guard<'a, T> like this, I think instead of only having push_unchecked(), we should have two different functions: push_unchecked_front(), which replaces the name of Guard<'a, T>'s push_unchecked(), and push_unchecked_back(), which is what GuardBack<'a, T>'s push_unchecked() does. On a nit, I do think we can give it a better name than Guard<'a,T> (ChunkGuard<'a, T>?), but I don't think that's too important to worry about since this struct is private.

Yeah, I get the idea and it does reduce the number of structs on paper - but it also pulls in a lot of clever stuff (generics, TypeId, 'static bounds) for something that’s really just an internal guard.

For me, keeping Guard and GuardBack separate keeps the Drop logic dead simple and very obvious - which matters, because that’s the part doing the safety work. One drops 0..n, the other drops len-n..len. You read it once and you’re done.

How about a simple enum instead:

enum FillDirection {
  Forwards,
  Backwards,
}

Let's not overcomplicate things, this is fine as is.

How about a simple enum instead:

enum FillDirection {
  Forwards,
  Backwards,
}

This should probably be the same as for the Guard which reads:
impl<T: [const] Destruct> const Drop for Guard<'_, T> {

I'd leave that for when it is actually used in const functions.

" in order to avoid needing to monomorphize for every array length."

Like the other versions clarify their existence.

I'd leave that for when it is actually used in const functions.

Let's not overcomplicate things, this is fine as is.

I'd add a note on the ordering within the array (and a short explanation why this is not equivalent to .rev().next_chunk().

Do this part in a separate PR, or at least a separate commit. Optimizations shouldn't be tied with new features, both for obvious history and for ability to revert.

Update the PR title based on what you decide as well.