nitdoc: Document constraints on `nitdoc_id`.

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

diff --git a/src/doc/doc_model.nit b/src/doc/doc_model.nit
index 9794beb..3a560f5 100644 (file)
--- a/src/doc/doc_model.nit
+++ b/src/doc/doc_model.nit
@@ -16,29 +16,11 @@
 module doc_model
 
 import model_utils
-import docdown
+import doc_down
 import doc_templates
 import ordered_tree
 import model_ext
 
-
-################################################################################
-# Additions to Nit entities.
-
-redef class MDoc
-       # Comment synopsys HTML escaped
-       fun short_comment: String do return content.first.html_escape
-
-       # Full comment HTML escaped
-       fun full_comment: String do return content.join("\n").html_escape
-
-       # Synopsys in a template
-       fun tpl_short_comment: Streamable do return short_markdown
-
-       # Full comment in a template
-       fun tpl_comment: Streamable do return full_markdown
-end
-
 redef class Location
        # Github url based on this location
        fun github(gitdir: String): String do
@@ -53,10 +35,18 @@ redef class MEntity
        # HTML Escaped name
        fun nitdoc_name: String is abstract
 
-       # Used as HTML unique ids
+       # ID used as a HTML 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 is abstract
 
-       # URL of this entity Nitdoc page
+       # URL of this entity’s Nitdoc page.
        fun nitdoc_url: String is abstract
 
        # A template link to the mentity `nitdoc_id`
@@ -112,7 +102,7 @@ redef class MEntity
                lnk.add tpl_link
                if mdoc != null then
                        lnk.add ": "
-                       lnk.add mdoc.short_markdown
+                       lnk.add mdoc.tpl_short_comment
                end
                return new TplListItem.with_content(lnk)
        end
@@ -142,7 +132,7 @@ redef class MConcern
                lnk.add tpl_anchor
                if mdoc != null then
                        lnk.add ": "
-                       lnk.add mdoc.short_markdown
+                       lnk.add mdoc.tpl_short_comment
                end
                return new TplListItem.with_content(lnk)
        end
@@ -237,7 +227,7 @@ redef class MModule
        redef fun tpl_declaration do
                var tpl = new Template
                tpl.add "<span>module "
-               tpl.add tpl_link
+               tpl.add tpl_namespace
                tpl.add "</span>"
                return tpl
        end
@@ -265,7 +255,7 @@ end
 
 redef class MClass
        redef fun nitdoc_name do return name.html_escape
-       redef fun nitdoc_id do return "{intro_mmodule.mgroup.mproject}__{name.to_cmangle}"
+       redef fun nitdoc_id do return "{intro_mmodule.nitdoc_id}__{name.to_cmangle}"
        redef fun nitdoc_url do return "class_{nitdoc_id}.html"
        redef fun mdoc do return intro.mdoc
 
@@ -405,10 +395,10 @@ redef class MClassDef
                lnk.add tpl_link
                if mdoc != null then
                        lnk.add ": "
-                       lnk.add mdoc.short_markdown
+                       lnk.add mdoc.tpl_short_comment
                else if mclass.intro.mdoc != null then
                        lnk.add ": "
-                       lnk.add mclass.intro.mdoc.short_markdown
+                       lnk.add mclass.intro.mdoc.tpl_short_comment
                end
                return new TplListItem.with_content(lnk)
        end
@@ -552,10 +542,10 @@ redef class MPropDef
                lnk.add anchor
                if mdoc != null then
                        lnk.add ": "
-                       lnk.add mdoc.short_markdown
+                       lnk.add mdoc.tpl_short_comment
                else if mproperty.intro.mdoc != null then
                        lnk.add ": "
-                       lnk.add mproperty.intro.mdoc.short_markdown
+                       lnk.add mproperty.intro.mdoc.tpl_short_comment
                end
                return new TplListItem.with_content(lnk)
        end
@@ -570,7 +560,7 @@ redef class MPropDef
                lnk.add anchor
                if mdoc != null then
                        lnk.add ": "
-                       lnk.add mdoc.short_markdown
+                       lnk.add mdoc.tpl_short_comment
                end
                var li = new TplListItem.with_content(lnk)
                li.css_classes.add "signature"
@@ -578,6 +568,17 @@ redef class MPropDef
        end
 end
 
+redef class MAttributeDef
+       redef fun tpl_signature do
+               var tpl = new Template
+               if static_mtype != null then
+                       tpl.add ": "
+                       tpl.add static_mtype.tpl_signature
+               end
+               return tpl
+       end
+end
+
 redef class MMethod
        redef fun tpl_signature do
                var tpl = new Template
@@ -612,28 +613,6 @@ redef class MVirtualTypeDef
        end
 end
 
-redef class MInnerClass
-       redef fun nitdoc_url do return inner.nitdoc_url
-       redef fun tpl_signature do return inner.tpl_signature
-end
-
-redef class MInnerClassDef
-       redef fun nitdoc_url do return inner.nitdoc_url
-
-       redef fun tpl_anchor do return inner.tpl_anchor
-       redef fun tpl_link do return inner.tpl_link
-       redef fun tpl_signature do return inner.tpl_signature
-
-       redef fun tpl_definition do
-               var tpl = new TplClassDefinition
-               tpl.namespace = mclassdef.tpl_namespace
-               if mdoc != null then
-                       tpl.comment = mdoc.tpl_comment
-               end
-               return tpl
-       end
-end
-
 redef class MType
        fun tpl_signature: Template is abstract
 end
@@ -762,3 +741,25 @@ redef class MRawType
                return tpl
        end
 end
+
+redef class MInnerClass
+       redef fun nitdoc_url do return inner.nitdoc_url
+       redef fun tpl_signature do return inner.tpl_signature
+end
+
+redef class MInnerClassDef
+       redef fun nitdoc_url do return inner.nitdoc_url
+
+       redef fun tpl_anchor do return inner.tpl_anchor
+       redef fun tpl_link do return inner.tpl_link
+       redef fun tpl_signature do return inner.tpl_signature
+
+       redef fun tpl_definition do
+               var tpl = new TplClassDefinition
+               tpl.namespace = mclassdef.tpl_namespace
+               if mdoc != null then
+                       tpl.comment = mdoc.tpl_comment
+               end
+               return tpl
+       end
+end