Rename forget to forget_elements and add safety comments

src/base/array_storage.rs

@@ -132,7 +132,7 @@ where
     }
 
     #[inline]
-    fn forget(self) {
+    fn forget_elements(self) {
         // No additional cleanup required.
         std::mem::forget(self);
     }

src/base/default_allocator.rs

@@ -211,7 +211,7 @@ where
         // Safety:
         // - We don’t care about dropping elements because the caller is responsible for dropping things.
         // - We forget `buf` so that we don’t drop the other elements, but ensure the buffer itself is cleaned up.
-        buf.forget();
+        buf.forget_elements();
 
         res
     }
@@ -242,7 +242,7 @@ where
         // Safety:
         // - We don’t care about dropping elements because the caller is responsible for dropping things.
         // - We forget `buf` so that we don’t drop the other elements.
-        buf.forget();
+        buf.forget_elements();
 
         res
     }
@@ -273,7 +273,7 @@ where
         // Safety:
         // - We don’t care about dropping elements because the caller is responsible for dropping things.
         // - We forget `buf` so that we don’t drop the other elements.
-        buf.forget();
+        buf.forget_elements();
 
         res
     }

src/base/matrix_view.rs

@@ -231,7 +231,7 @@ macro_rules! storage_impl(
             }
 
             #[inline]
-            fn forget(self) {
+            fn forget_elements(self) {
                 // No cleanup required.
             }
         }

src/base/storage.rs

@@ -150,8 +150,8 @@ pub unsafe trait Storage<T: Scalar, R: Dim, C: Dim = U1>: RawStorage<T, R, C> {
     where
         DefaultAllocator: Allocator<R, C>;
 
-    /// Cleans up the storage without calling the destructors on the contained elements.
-    fn forget(self);
+    /// Drops the storage without calling the destructors on the contained elements.
+    fn forget_elements(self);
 }
 
 /// Trait implemented by matrix data storage that can provide a mutable access to its elements.

src/base/vec_storage.rs

@@ -283,8 +283,13 @@ where
     }
 
     #[inline]
-    fn forget(mut self) {
-        // Set length to 0 so element destructors are not called.
+    fn forget_elements(mut self) {
+        // SAFETY: setting the length to zero is always sound, as it does not
+        // cause any memory to be deemed initialized. If the previous length was
+        // non-zero, it is equivalent to using mem::forget to leak each element.
+        // Then, when this function returns, self.data is dropped, freeing the
+        // allocated memory, but the elements are not dropped because they are
+        // now considered uninitialized.
         unsafe { self.data.set_len(0) };
     }
 }
@@ -340,8 +345,13 @@ where
     }
 
     #[inline]
-    fn forget(mut self) {
-        // Set length to 0 so element destructors are not called.
+    fn forget_elements(mut self) {
+        // SAFETY: setting the length to zero is always sound, as it does not
+        // cause any memory to be deemed initialized. If the previous length was
+        // non-zero, it is equivalent to using mem::forget to leak each element.
+        // Then, when this function returns, self.data is dropped, freeing the
+        // allocated memory, but the elements are not dropped because they are
+        // now considered uninitialized.
         unsafe { self.data.set_len(0) };
     }
 }