loader: improve documentation

[nit.git] / src / model / mmodule.nit

diff --git a/src/model/mmodule.nit b/src/model/mmodule.nit
index e66f164..db4b8c6 100644 (file)
--- a/src/model/mmodule.nit
+++ b/src/model/mmodule.nit
@@ -18,11 +18,15 @@
 module mmodule
 
 import location
-import mproject
+import mpackage
 private import more_collections
 
 # The container class of a Nit object-oriented model.
+#
 # A model knows modules, classes and properties and can retrieve them.
+#
+# However, a model is not a program or a library as it can contains modules
+# found by the system (including broken ones) but not used.
 redef class Model
        # All known modules
        var mmodules = new Array[MModule]
@@ -73,9 +77,17 @@ class MModule
        # The model considered
        redef var model: Model
 
-       # The group of module in the project if any
+       # The group of module in the package if any
        var mgroup: nullable MGroup
 
+       # The package of the module if any
+       # Safe alias for `mgroup.mpackage`
+       fun mpackage: nullable MPackage
+       do
+               var g = mgroup
+               if g == null then return null else return g.mpackage
+       end
+
        # The short name of the module
        redef var name: String
 
@@ -90,17 +102,33 @@ class MModule
 
        # The canonical name of the module.
        #
-       # It is usually the `name` prefixed by the project's name.
-       # Example: `"project::name"`
+       # It is usually the `name` prefixed by the package's name.
+       # Example: `"package::name"`
        #
-       # If both names are the same (of if the module is project-less), then
+       # If both names are the same (of if the module is package-less), then
        # the short-name is used alone.
        redef var full_name is lazy do
                var mgroup = self.mgroup
-               if mgroup == null or mgroup.mproject.name == self.name then
+               if mgroup == null or mgroup.mpackage.name == self.name then
                        return self.name
                else
-                       return "{mgroup.mproject.name}::{self.name}"
+                       return "{mgroup.mpackage.name}::{self.name}"
+               end
+       end
+
+       # The namespace used for entities according to their visibility `v`.
+       #
+       # Public entities use only the package as a namespace.
+       # Private entities use the `full_name` (i.e. "package::module")
+       #
+       # This method is used by entities to implement their `full_name`.
+       fun namespace_for(v: MVisibility): String do
+               if v <= private_visibility then return full_name
+               var mgroup = self.mgroup
+               if mgroup == null then
+                       return full_name
+               else
+                       return mgroup.mpackage.full_name
                end
        end
 
@@ -109,14 +137,27 @@ class MModule
        redef var c_name: String is lazy do
                var g = mgroup
                var res
-               if g != null and g.mproject.name != name then
-                       res = g.mproject.name.to_cmangle + "__" + name.to_cmangle
+               if g != null and g.mpackage.name != name then
+                       res = g.mpackage.name.to_cmangle + "__" + name.to_cmangle
                else
                        res = name.to_cmangle
                end
                return res
        end
 
+       # C identifier version of `namespace_for`.
+       # See `c_name`
+       #
+       # This method is used by entities to implement their `c_name`.
+       fun c_namespace_for(v: MVisibility): String do
+               if v <= private_visibility then return c_name
+               var mgroup = self.mgroup
+               if mgroup == null then
+                       return c_name
+               else
+                       return mgroup.mpackage.c_name
+               end
+       end
 
        # Create a new empty module and register it to a model
        init
@@ -134,11 +175,9 @@ class MModule
        end
 
        # Register the imported modules (ie "import some_module")
-       # This function can only invoked once by mmodule.
        # The visibility must be set with `set_visibility_for`.
        fun set_imported_mmodules(imported_mmodules: Array[MModule])
        do
-               assert unique_invocation: self.in_importation.direct_greaters.is_empty
                for m in imported_mmodules do
                        self.model.mmodule_importation_hierarchy.add_edge(self, m)
                end
@@ -203,5 +242,18 @@ class MModule
        # exposed to the final user.
        var is_fictive: Bool = false is writable
 
+       # Is `self` a unit test module used by `nitunit`?
+       var is_test_suite: Bool = false is writable
+
+       # Get the first non `is_fictive` module greater than self
+       fun first_real_mmodule: MModule
+       do
+               var mmodule = self
+               while mmodule.is_fictive do
+                       mmodule = mmodule.in_importation.direct_greaters.first
+               end
+               return mmodule
+       end
+
        redef fun parent_concern do return mgroup
 end