Merge: Annotation lateinit

[nit.git] / src / doc / doc_base.nit

diff --git a/src/doc/doc_base.nit b/src/doc/doc_base.nit
index 615f98c..8f0467d 100644 (file)
--- a/src/doc/doc_base.nit
+++ b/src/doc/doc_base.nit
@@ -16,7 +16,8 @@
 module doc_base
 
 import toolcontext
-import doc_model # FIXME maintain compatibility with old templates.
+import model_utils
+import model_ext
 
 # The model of a Nitdoc documentation.
 #
@@ -26,16 +27,26 @@ import doc_model # FIXME maintain compatibility with old templates.
 # It is a placeholder to share data between each phase.
 class DocModel
 
-       # `DocPage` composing the documentation.
+       # `DocPage` composing the documentation associated to their ids.
        #
        # This is where `DocPhase` store and access pages to produce documentation.
-       var pages = new Array[DocPage]
+       #
+       # See `add_page`.
+       var pages: Map[String, DocPage] = new HashMap[String, DocPage]
 
        # Nit `Model` from which we extract the documentation.
        var model: Model is writable
 
        # The entry point of the `model`.
        var mainmodule: MModule is writable
+
+       # Add a `page` to this documentation.
+       fun add_page(page: DocPage) do
+               if pages.has_key(page.id) then
+                       print "Warning: multiple page with the same id `{page.id}`"
+               end
+               pages[page.id] = page
+       end
 end
 
 # A documentation page abstraction.
@@ -44,6 +55,17 @@ end
 # the page.
 class DocPage
 
+       # Page uniq id.
+       #
+       # The `id` is used as name for the generated file corresponding to the page
+       # (if any).
+       # Because multiple pages can be generated in the same directory it should be
+       # uniq.
+       #
+       # The `id` can also be used to establish links between pages (HTML links,
+       # HTML anchors, vim links, etc.).
+       var id: String is writable
+
        # Title of this page.
        var title: String is writable
 
@@ -67,7 +89,7 @@ end
 abstract class DocComposite
 
        # Parent element.
-       var parent: nullable DocComposite = null
+       var parent: nullable DocComposite = null is writable
 
        # Does `self` have a `parent`?
        fun is_root: Bool do return parent == null
@@ -84,8 +106,15 @@ abstract class DocComposite
        #
        # Shortcut for `children.add`.
        fun add_child(child: DocComposite) do
+               child.parent = self
                children.add child
        end
+
+       # Depth of `self` in the composite tree.
+       fun depth: Int do
+               if parent == null then return 0
+               return parent.depth + 1
+       end
 end
 
 # The `DocComposite` element that contains all the other.
@@ -219,3 +248,36 @@ class PropertyGroup[E: MProperty]
        # The title of the group, as displayed to the user.
        var title: String
 end
+
+redef class MEntity
+       # ID used as a unique ID and in file names.
+       #
+       # **Must** match the following (POSIX ERE) regular expression:
+       #
+       # ~~~POSIX ERE
+       # ^[A-Za-z_][A-Za-z0-9._-]*$
+       # ~~~
+       #
+       # That way, the ID is always a valid URI component and a valid XML name.
+       fun nitdoc_id: String do return full_name.to_cmangle
+
+       # Name displayed in console for debug and tests.
+       fun nitdoc_name: String do return name.html_escape
+end
+
+redef class MModule
+
+       # Avoid id conflict with group
+       redef fun nitdoc_id do
+               if mgroup == null then return super
+               return "{mgroup.full_name}::{full_name}".to_cmangle
+       end
+end
+
+redef class MClassDef
+       redef fun nitdoc_name do return mclass.nitdoc_name
+end
+
+redef class MPropDef
+       redef fun nitdoc_name do return mproperty.nitdoc_name
+end