add missing comments

src/rt/dmain2.d

@@ -1,7 +1,7 @@
 /**
  * Contains main program entry point and support routines.
  *
- * Copyright: Copyright Digital Mars 2000 - 2012.
+ * Copyright: Copyright Digital Mars 2000 - 2013.
  * License: Distributed under the
  *      $(LINK2 http://www.boost.org/LICENSE_1_0.txt, Boost Software License 1.0).
  *    (See accompanying file LICENSE)
@@ -82,6 +82,12 @@ extern (C)
     alias void  function()      gcClrFn;
 }
 
+/*******************************************
+ * Loads a DLL with the name 'name'.
+ * Returns:
+ *      handle to the DLL if successfully loaded
+ *      null if failure
+ */
 extern (C) void* rt_loadLibrary(in char[] name)
 {
     version (Windows)
@@ -108,6 +114,7 @@ extern (C) void* rt_loadLibrary(in char[] name)
         buf[len] = '\0';
 
         // BUG: LoadLibraryW() call calls rt_init(), which fails if proxy is not set!
+        // (What? LoadLibraryW() is a Windows API call, it shouldn't call rt_init().)
         auto mod = LoadLibraryW(buf);
         if (mod is null)
             return mod;
@@ -125,6 +132,14 @@ extern (C) void* rt_loadLibrary(in char[] name)
     }
 }
 
+/*************************************
+ * Unloads DLL that was previously loaded by rt_loadLibrary().
+ * Input:
+ *      ptr     the handle returned by rt_loadLibrary()
+ * Returns:
+ *      true    succeeded
+ *      false   some failure happened
+ */
 extern (C) bool rt_unloadLibrary(void* ptr)
 {
     version (Windows)
@@ -156,13 +171,16 @@ extern (C) bool runModuleUnitTests();
 //extern (C) void onUnicodeError(string msg, size_t idx);
 
 /***********************************
- * These are internal callbacks for various language errors.
+ * Function calls to these are generated by the compiler and inserted into
+ * the object code.
  */
 
 extern (C)
 {
     // Use ModuleInfo to get file name for "m" versions
 
+    /* One of these three is called upon an assert() fail.
+     */
     void _d_assertm(ModuleInfo* m, uint line)
     {
         onAssertError(m.name, line);
@@ -178,6 +196,8 @@ extern (C)
         onAssertError(file, line);
     }
 
+    /* One of these three is called upon an assert() fail inside of a unittest block
+     */
     void _d_unittestm(ModuleInfo* m, uint line)
     {
         _d_unittest(m.name, line);
@@ -193,36 +213,43 @@ extern (C)
         _d_unittest_msg("unittest failure", file, line);
     }
 
+    /* Called when an array index is out of bounds
+     */
     void _d_array_bounds(ModuleInfo* m, uint line)
     {
         onRangeError(m.name, line);
     }
 
+    /* Called when a switch statement has no DefaultStatement, yet none of the cases match
+     */
     void _d_switch_error(ModuleInfo* m, uint line)
     {
         onSwitchError(m.name, line);
     }
-}
 
-extern (C) void _d_hidden_func()
-{
-    Object o;
-    version(D_InlineAsm_X86)
-        asm
-        {
-            mov o, EAX;
-        }
-    else version(D_InlineAsm_X86_64)
-        asm
-        {
-            mov o, RDI;
-        }
-    else
-        static assert(0, "unknown os");
+    void _d_hidden_func()
+    {
+        Object o;
+        version(D_InlineAsm_X86)
+            asm
+            {
+                mov o, EAX;
+            }
+        else version(D_InlineAsm_X86_64)
+            asm
+            {
+                mov o, RDI;
+            }
+        else
+            static assert(0, "unknown os");
 
-    onHiddenFuncError(o);
+        onHiddenFuncError(o);
+    }
 }
 
+/* To get out-of-band access to the args[] passed to main().
+ */
+
 __gshared string[] _d_args = null;
 
 extern (C) string[] rt_args()
@@ -234,17 +261,19 @@ extern (C) string[] rt_args()
 // be fine to leave it as __gshared.
 extern (C) __gshared bool rt_trapExceptions = true;
 
-void _d_criticalInit()
-{
-  _STI_monitor_staticctor();
-  _STI_critical_init();
-}
-
 alias void delegate(Throwable) ExceptionHandler;
 
+/**********************************************
+ * Initialize druntime.
+ * If it fails, call dg. Except that what dg might be
+ * able to do is undetermined, since the state of druntime
+ * will not be known.
+ * This needs rethinking.
+ */
 extern (C) bool rt_init(ExceptionHandler dg = null)
 {
-    _d_criticalInit();
+    _STI_monitor_staticctor();
+    _STI_critical_init();
 
     try
     {
@@ -258,21 +287,29 @@ extern (C) bool rt_init(ExceptionHandler dg = null)
     }
     catch (Throwable e)
     {
+        /* Note that if we get here, the runtime is in an unknown state.
+         * I'm not sure what the point of calling dg is.
+         */
         if (dg)
             dg(e);
         else
             throw e;    // rethrow, don't silently ignore error
+        /* Rethrow, and the two STD functions aren't called?
+         * This needs rethinking.
+         */
     }
-    _d_criticalTerm();
+    _STD_critical_term();
+    _STD_monitor_staticdtor();
     return false;
 }
 
-void _d_criticalTerm()
-{
-  _STD_critical_term();
-  _STD_monitor_staticdtor();
-}
-
+/**********************************************
+ * Terminate use of druntime.
+ * If it fails, call dg. Except that what dg might be
+ * able to do is undetermined, since the state of druntime
+ * will not be known.
+ * This needs rethinking.
+ */
 extern (C) bool rt_term(ExceptionHandler dg = null)
 {
     try
@@ -291,11 +328,17 @@ extern (C) bool rt_term(ExceptionHandler dg = null)
     }
     finally
     {
-        _d_criticalTerm();
+        _STD_critical_term();
+        _STD_monitor_staticdtor();
     }
     return false;
 }
 
+/***********************************
+ * Provide out-of-band access to the original C argc/argv
+ * passed to this program via main(argc,argv).
+ */
+
 struct CArgs
 {
     int argc;
@@ -357,8 +400,10 @@ version (Solaris) extern (C) int _main(int argc, char** argv)
  */
 extern (C) int _d_run_main(int argc, char **argv, MainFunc mainFunc)
 {
+    // Remember the original C argc/argv
     _cArgs.argc = argc;
     _cArgs.argv = argv;
+
     int result;
 
     version (OSX)
@@ -411,9 +456,16 @@ extern (C) int _d_run_main(int argc, char **argv, MainFunc mainFunc)
     _STI_monitor_staticctor();
     _STI_critical_init();
 
+    // Allocate args[] on the stack
     char[][] args = (cast(char[]*) alloca(argc * (char[]).sizeof))[0 .. argc];
+
     version (Windows)
     {
+        /* Because we want args[] to be UTF-8, and Windows doesn't guarantee that,
+         * we ignore argc/argv and go get the Windows command line again as UTF-16.
+         * Then, reparse into wargc/wargs, and then use Windows API to convert
+         * to UTF-8.
+         */
         const wchar_t* wCommandLine = GetCommandLineW();
         immutable size_t wCommandLineLength = wcslen(wCommandLine);
         int wargc;
@@ -456,6 +508,10 @@ extern (C) int _d_run_main(int argc, char **argv, MainFunc mainFunc)
     else
         static assert(0);
 
+    /* Create a copy of args[] on the stack, and set the global _d_args to refer to it.
+     * Why a copy instead of just using args[] is unclear.
+     * This also means that when this function returns, _d_args will refer to garbage.
+     */
     {
         auto buff = cast(char[]*) alloca(argc * (char[]).sizeof + totalArgsLength);