Document all `unsafe` blocks.

[reitermarkus]

All unsafe blocks should be documented with a SAFETY comment and be scoped as closely as possible.

After all are documented, the clippy::undocumented_unsafe_blocks lint should be enabled.

Also, the unsafe_op_in_unsafe_fn lint should be enabled (default in edition 2024), so that unsafe blocks in unsafe functions are also documented.

[Mortano]

I should be able to help with that, if the help is still wanted. Are there any contribution guidelines for first-time contributors?

[zeenix]

I should be able to help with that, if the help is still wanted.

I'm pretty sure it is. :) Thanks.

Are there any contribution guidelines for first-time contributors?

None really. We do have a CoC (see CODE_OF_CONDUCT.md file) but that's pretty normal these days.

[Mortano]

Ok I'll start working on this then :)

[Mortano]

Do you have a preference as to how detailed the documentation should be? Unsafe Rust is a tricky beast and many of the unsafe functions that are used have quite a long list of safety requirements. The way I'm approaching this now is to go through these lists and verify that each requirement is met and document that accordingly, but that makes the SAFETY comments quite long in some cases. Here is one example in DequeInner::make_contiguous, which uses a lot of pointer arithmetics and raw memcpy:

...
} else if free >= back_len {
    // there is enough free space to copy the tail in one go,
    // this means that we first shift the head forwards, and then
    // copy the tail to the correct position.
    //
    // from: FGH....ABCDE
    // to:   ...ABCDEFGH.

    // SAFETY: Explaining it visually is easier:
    // step 1:   FGH....ABCDE
    //              |   |
    //              1   2
    //           |__|___|___|
    //  back_len---^  ^   ^---- front_len
    //              free
    // step 2:   FGHABCDE....
    //           |       |
    //           3       4
    // Pointers: 1: `buffer_ptr.add(self.back)`
    //           2: `buffer_ptr.add(self.front)`
    //           3: `buffer_ptr`
    //           4: `buffer_ptr.add(self.back + front_len)`
    // All pointers are clearly within the underlying buffer and are properly aligned, meeting the first safety
    // requirement for `ptr.add` and the `ptr::copy...` variants.
    // In step 1 above, we see that pointer 1 is always `<=` than pointer 2, so the copy stays within the bounds
    // of the buffer, but it might overlap, hence the usage of `ptr::copy`
    // In step 2 above, we see that the target memory region does not overlap with the source region, as pointer 4
    // is larger than pointer 3 plus `back_len`. Finally the branch condition assures that the gap is large enough
    // to copy `back_len` elements into
    unsafe {
        ptr::copy(
            buffer_ptr.add(self.front),
            buffer_ptr.add(self.back),
            front_len,
        );
        // FGHABCDE....
        ptr::copy_nonoverlapping(
            buffer_ptr,
            buffer_ptr.add(self.back + front_len),
            back_len,
        );
        // ...ABCDEFGH.
    }

    self.front = back;
    self.back = 0;
}
...

The unit tests should catch the various edge cases that the algorithm itself has, so maybe I could reduce the comment length and simply state "We ensure that all pointers always stay within their bounds through the tests"?

[zeenix]

Do you have a preference as to how detailed the documentation should be?

I can't speak for @reitermarkus here but IMO while your attention to detail is appreciated, I really don't think we need this level of detail. Typically, you'd just have a bullet list for each safety requirement mentioned in the documentation of the API being used, shortly explaining why/how the requirement is satisfied.

I typically keep them short but probably that's a bit too short. :)

[Mortano]

Ok I'll try to keep it more concise then, thanks for the clarification

[Mortano]

I found one potential safety violation related to #579 (see my comment in there). I'll continue checking and commenting the rest of the unsafe code and will comment here if I find something else, then we can discuss how to deal with each issue.