Merge pull request #3464 from WalterBright/ModuleInfo

document ModuleInfo

Author: RazvanN7

spec/abi.dd

@@ -957,32 +957,70 @@ $(H2 $(LNAME2 garbage_collection, Garbage Collection))
 
         $(P The interface to this is found in Druntime's $(DRUNTIMESRC core/gc/gcinterface.d).)
 
-$(H2 $(LNAME2 runtime_helper_functions, Runtime Helper Functions))
+$(H2 $(LNAME2 ModuleInfo, ModuleInfo Instance))
 
-        $(P These are found in Druntime's $(DRUNTIMESRC rt/).)
+        $(P An instance of $(LINK2 https://dlang.org/phobos/object.html#.ModuleInfo, `ModuleInfo`)
+        is generated by the compiler and inserted into the object file for every module.
+        `ModuleInfo` contains information about the module that is useful to the D runtime library:
+        )
+
+        $(UL
+        $(LI If the module has a static constructor, static destructor, shared static constructor, or shared static destructor.)
+        $(LI A reference to any unit tests defined by the module.)
+        $(LI An array of references to any imported modules that have one or more of:
+            $(OL
+            $(LI static constructors)
+            $(LI static destructors)
+            $(LI shared static constructors)
+            $(LI shared static destructors)
+            $(LI unit tests)
+            $(LI transitive imports of any module that contains one or more of 1..5)
+            $(LI order independent constructors (currently needed for implementing
+            $(DDSUBLINK dmd, switch-cov, $(TT -cov))))
+            )
+            This enables the runtime to run the unit tests,
+            the module constructors in a depth-first order,
+            and the module destructors in the reverse order.
+        )
+
+        $(LI An array of references to `ClassInfo` for each class defined in the module.
+        $(NOTE this feature may be removed.))
+        )
+
+        $(P `ModuleInfo` is defined in Druntime's $(DRUNTIMESRC object.d).)
+
+        $(P Modules compiled with $(DDSUBLINK dmd, switch-betterC, $(TT -betterC))
+        do not have a `ModuleInfo` instance generated, because such modules must work
+        without the D runtime library.
+        Similarly, $(DDLINK spec/importc, ImportC, ImportC) modules do not generate a `ModuleInfo`.
+        )
 
-$(H2 $(LNAME2 module_init_and_fina, Module Initialization and Termination))
+$(H3 $(LNAME2 module_init_and_fina, Module Initialization and Termination))
 
         $(P All the static constructors for a module are aggregated into a
         single function, and a pointer to that function is inserted
-        into the ctor member of the ModuleInfo instance for that
+        into the ctor member of the `ModuleInfo` instance for that
         module.
         )
 
         $(P All the static destructors for a module are aggregated into a
         single function, and a pointer to that function is inserted
-        into the dtor member of the ModuleInfo instance for that
+        into the dtor member of the `ModuleInfo` instance for that
         module.
         )
 
-$(H2 $(LNAME2 unit_testing, Unit Testing))
+$(H3 $(LNAME2 unit_testing, Unit Testing))
 
         $(P All the unit tests for a module are aggregated into a
         single function, and a pointer to that function is inserted
-        into the unitTest member of the ModuleInfo instance for that
+        into the unitTest member of the `ModuleInfo` instance for that
         module.
         )
 
+$(H2 $(LNAME2 runtime_helper_functions, Runtime Helper Functions))
+
+        $(P These are found in Druntime's $(DRUNTIMESRC rt/).)
+
 $(H2 $(LNAME2 symbolic_debugging, Symbolic Debugging))
 
         $(P D has types that are not represented in existing C or C++ debuggers.

spec/betterc.dd

@@ -122,7 +122,7 @@ $(H2 $(LNAME2 consequences, Unavailable Features))
 
 $(OL
     $(LI Garbage Collection)
-    $(LI TypeInfo and ModuleInfo)
+    $(LI TypeInfo and (DDSUBLINK abi, ModuleInfo, $(TT ModuleInfo)))
     $(LI Classes)
     $(LI Built-in threading (e.g. $(MREF core, thread)))
     $(LI Dynamic arrays (though slices of static arrays work) and associative arrays)

spec/ddoc.dd

@@ -905,7 +905,7 @@ $(P
     $(LI Postblits)
     $(LI Destructors)
     $(LI Static constructors and static destructors)
-    $(LI Class info, type info, and module info)
+    $(LI Class info, type info, and $(DDSUBLINK abi, ModuleInfo, module info))
     )
 
 $(H2 $(LNAME2 macros, Macros))

spec/version.dd

@@ -321,7 +321,7 @@ $(H3 $(LEGACY_LNAME2 PredefinedVersions, predefined-versions, Predefined Version
                 (command line switch $(DDSUBLINK dmd, switch-betterC, $(TT -betterC))) is being generated))
         $(TROW $(ARGS $(D D_Exceptions)) , $(ARGS Exception handling is supported.  Evaluates to `false` when compiling with
                 command line switch $(DDSUBLINK dmd, switch-betterC, $(TT -betterC))))
-        $(TROW $(ARGS $(D D_ModuleInfo)) , $(ARGS `ModuleInfo` is supported.  Evaluates to `false` when compiling with
+        $(TROW $(ARGS $(D D_ModuleInfo)) , $(ARGS $(DDSUBLINK abi, ModuleInfo, $(TT ModuleInfo)) is supported.  Evaluates to `false` when compiling with
                 command line switch $(DDSUBLINK dmd, switch-betterC, $(TT -betterC))))
         $(TROW $(ARGS $(D D_TypeInfo)) , $(ARGS Runtime type information (a.k.a `TypeInfo`) is supported.  Evaluates to `false` when compiling with
                 command line switch $(DDSUBLINK dmd, switch-betterC, $(TT -betterC))))