Add some comments.

Also use `Default::default()` in one `TypedArena::default()`, for
consistency with `DroplessArena::default()`.

compiler/rustc_arena/src/lib.rs

@@ -111,7 +111,7 @@ impl<T> Default for TypedArena<T> {
             // alloc() will trigger a grow().
             ptr: Cell::new(ptr::null_mut()),
             end: Cell::new(ptr::null_mut()),
-            chunks: RefCell::new(vec![]),
+            chunks: Default::default(),
             _own: PhantomData,
         }
     }
@@ -325,13 +325,17 @@ unsafe impl<#[may_dangle] T> Drop for TypedArena<T> {
 
 unsafe impl<T: Send> Send for TypedArena<T> {}
 
+/// An arena that can hold objects of multiple different types that impl `Copy`
+/// and/or satisfy `!mem::needs_drop`.
 pub struct DroplessArena {
     /// A pointer to the start of the free space.
     start: Cell<*mut u8>,
 
     /// A pointer to the end of free space.
     ///
-    /// The allocation proceeds from the end of the chunk towards the start.
+    /// The allocation proceeds downwards from the end of the chunk towards the
+    /// start. (This is slightly simpler and faster than allocating upwards,
+    /// see <https://fitzgeraldnick.com/2019/11/01/always-bump-downwards.html>.)
     /// When this pointer crosses the start pointer, a new chunk is allocated.
     end: Cell<*mut u8>,
 
@@ -516,6 +520,10 @@ impl DroplessArena {
     }
 }
 
+// Declare an `Arena` containing one dropless arena and many typed arenas (the
+// types of the typed arenas are specified by the arguments). The dropless
+// arena will be used for any types that impl `Copy`, and also for any of the
+// specified types that satisfy `!mem::needs_drop`.
 #[rustc_macro_transparency = "semitransparent"]
 pub macro declare_arena([$($a:tt $name:ident: $ty:ty,)*]) {
     #[derive(Default)]
@@ -532,6 +540,7 @@ pub macro declare_arena([$($a:tt $name:ident: $ty:ty,)*]) {
         ) -> &'a mut [Self];
     }
 
+    // Any type that impls `Copy` can be arena-allocated in the `DroplessArena`.
     impl<'tcx, T: Copy> ArenaAllocatable<'tcx, ()> for T {
         #[inline]
         fn allocate_on<'a>(self, arena: &'a Arena<'tcx>) -> &'a mut Self {
@@ -544,7 +553,6 @@ pub macro declare_arena([$($a:tt $name:ident: $ty:ty,)*]) {
         ) -> &'a mut [Self] {
             arena.dropless.alloc_from_iter(iter)
         }
-
     }
     $(
         impl<'tcx> ArenaAllocatable<'tcx, $ty> for $ty {
@@ -577,6 +585,7 @@ pub macro declare_arena([$($a:tt $name:ident: $ty:ty,)*]) {
             value.allocate_on(self)
         }
 
+        // Any type that impls `Copy` can have slices be arena-allocated in the `DroplessArena`.
         #[inline]
         pub fn alloc_slice<T: ::std::marker::Copy>(&self, value: &[T]) -> &mut [T] {
             if value.is_empty() {

compiler/rustc_hir/src/arena.rs

@@ -1,4 +1,4 @@
-/// This declares a list of types which can be allocated by `Arena`.
+/// This higher-order macro declares a list of types which can be allocated by `Arena`.
 ///
 /// Specifying the `decode` modifier will add decode impls for `&T` and `&[T]`,
 /// where `T` is the type listed. These impls will appear in the implement_ty_decoder! macro.

compiler/rustc_middle/src/arena.rs

@@ -1,4 +1,4 @@
-/// This declares a list of types which can be allocated by `Arena`.
+/// This higher-order macro declares a list of types which can be allocated by `Arena`.
 ///
 /// Specifying the `decode` modifier will add decode impls for `&T` and `&[T]` where `T` is the type
 /// listed. These impls will appear in the implement_ty_decoder! macro.