Edit rustc_arena::DropArena docs

- Add a "Safety" section, edit formatting for clarity
- Add missing punctuation in code comments

Author: pierwill

compiler/rustc_arena/src/lib.rs

@@ -568,10 +568,13 @@ impl Drop for DropType {
 }
 
 /// An arena which can be used to allocate any type.
+///
+/// # Safety
+///
 /// Allocating in this arena is unsafe since the type system
 /// doesn't know which types it contains. In order to
-/// allocate safely, you must store a PhantomData<T>
-/// alongside this arena for each type T you allocate.
+/// allocate safely, you must store a `PhantomData<T>`
+/// alongside this arena for each type `T` you allocate.
 #[derive(Default)]
 pub struct DropArena {
     /// A list of destructors to run when the arena drops.
@@ -589,7 +592,7 @@ impl DropArena {
         ptr::write(mem, object);
         let result = &mut *mem;
         // Record the destructor after doing the allocation as that may panic
-        // and would cause `object`'s destructor to run twice if it was recorded before
+        // and would cause `object`'s destructor to run twice if it was recorded before.
         self.destructors
             .borrow_mut()
             .push(DropType { drop_fn: drop_for_type::<T>, obj: result as *mut T as *mut u8 });
@@ -607,16 +610,16 @@ impl DropArena {
         let start_ptr = self.arena.alloc_raw(Layout::array::<T>(len).unwrap()) as *mut T;
 
         let mut destructors = self.destructors.borrow_mut();
-        // Reserve space for the destructors so we can't panic while adding them
+        // Reserve space for the destructors so we can't panic while adding them.
         destructors.reserve(len);
 
         // Move the content to the arena by copying it and then forgetting
-        // the content of the SmallVec
+        // the content of the SmallVec.
         vec.as_ptr().copy_to_nonoverlapping(start_ptr, len);
         mem::forget(vec.drain(..));
 
         // Record the destructors after doing the allocation as that may panic
-        // and would cause `object`'s destructor to run twice if it was recorded before
+        // and would cause `object`'s destructor to run twice if it was recorded before.
         for i in 0..len {
             destructors
                 .push(DropType { drop_fn: drop_for_type::<T>, obj: start_ptr.add(i) as *mut u8 });