Moar comments.

2 files changed, 22 insertions, 1 deletions

diff --git a/src/rtstartup/rsbegin.rs b/src/rtstartup/rsbegin.rs
index 17684b74b70..af9a01ea2e4 100644
--- a/src/rtstartup/rsbegin.rs
+++ b/src/rtstartup/rsbegin.rs
@@ -8,8 +8,21 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// rsbegin.o and rsend.o are the so called "compiler runtime startup objects".
+// They contain code needed to correctly initialize the compiler runtime.
+//
+// When an executable or dylib image is linked, all user code and libraries are
+// "sandwiched" between these two object files, so code or data from rsbegin.o
+// become first in the respective sections of the image, whereas code and data
+// from rsend.o become the last ones.  This effect can be used to place symbols
+// at the beginning or at the end of a section, as well as to insert any required
+// headers or footers.
+//
+// Note that the actual module entry point is located in the C runtime startup
+// object (usually called `crtX.o), which then invokes initialization callbacks
+// of other runtime components (registered via yet another special image section).
+
 #![feature(no_std)]
-#![feature(linkage)]
 
 #![crate_type="rlib"]
 #![no_std]
@@ -20,27 +33,33 @@ pub mod eh_frames
 {
     #[no_mangle]
     #[link_section = ".eh_frame"]
+    // Marks beginning of the stack frame unwind info section
     pub static __EH_FRAME_BEGIN__: [u8; 0] = [];
 
     // Scratch space for unwinder's internal book-keeping.
     // This is defined as `struct object` in $GCC/libgcc/unwind-dw2-fde.h.
     static mut obj: [isize; 6] = [0; 6];
 
+    // Unwind info registration/deregistration routines.
+    // See the docs of `unwind` module in libstd.
     extern {
         fn rust_eh_register_frames(eh_frame_begin: *const u8, object: *mut u8);
         fn rust_eh_unregister_frames(eh_frame_begin: *const u8, object: *mut u8);
     }
 
     unsafe fn init() {
+        // register unwind info on module startup
         rust_eh_register_frames(&__EH_FRAME_BEGIN__ as *const u8,
                                 &mut obj as *mut _ as *mut u8);
     }
 
     unsafe fn uninit() {
+        // unregister on shutdown
         rust_eh_unregister_frames(&__EH_FRAME_BEGIN__ as *const u8,
                                   &mut obj as *mut _ as *mut u8);
     }
 
+    // MSVC-specific init/uninit routine registration
     pub mod ms_init
     {
         // .CRT$X?? sections are roughly analogous to ELF's .init_array and .fini_array,
diff --git a/src/rtstartup/rsend.rs b/src/rtstartup/rsend.rs
index df7759877e9..ecb6a228e17 100644
--- a/src/rtstartup/rsend.rs
+++ b/src/rtstartup/rsend.rs
@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+// See rsbegin.rs for details.
+
 #![feature(no_std)]
 
 #![crate_type="rlib"]