add comments

Author: mark-i-m

src/librustc_mir/borrow_check/diagnostics/region_errors.rs

@@ -63,6 +63,9 @@ enum Trace {
 
 /// A collection of errors encountered during region inference. This is needed to efficiently
 /// report errors after borrow checking.
+///
+/// Usually we expect this to either be empty or contain a small number of items, so we can avoid
+/// allocation most of the time.
 crate type RegionErrors<'tcx> = smallvec::SmallVec<[RegionErrorKind<'tcx>; 4]>;
 
 #[derive(Clone, Debug)]

src/librustc_mir/borrow_check/mod.rs

@@ -1666,6 +1666,9 @@ impl<'cx, 'tcx> MirBorrowckCtxt<'cx, 'tcx> {
 
                         db.buffer(&mut self.errors_buffer);
                     } else {
+                        // We only report the first error, so as not to overwhelm the user. See
+                        // `RegRegionErrorKind` docs.
+                        //
                         // FIXME: currently we do nothing with these, but perhaps we can do better?
                         // FIXME: try collecting these constraints on the outlives suggestion
                         // builder. Does it make the suggestions any better?