X-Git-Url: http://nitlanguage.org diff --git a/src/doc/doc_model.nit b/src/doc/doc_model.nit index f13d69f..2c80ffb 100644 --- a/src/doc/doc_model.nit +++ b/src/doc/doc_model.nit @@ -16,23 +16,10 @@ module doc_model import model_utils -import markdown +import doc_down import doc_templates import ordered_tree - -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 +import model_ext redef class Location # Github url based on this location @@ -45,18 +32,27 @@ redef class Location end redef class MEntity - # HTML Escaped name - fun nitdoc_name: String is abstract - - # Used as HTML unique ids + # HTML-escaped name. + fun nitdoc_name: String do return name.html_escape + + # 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` fun tpl_anchor: TplLink do var tpl = new TplLink("#{nitdoc_id}", nitdoc_name) + var mdoc = mdoc_or_fallback if mdoc != null then tpl.title = mdoc.short_comment end @@ -66,6 +62,7 @@ redef class MEntity # A template link to the mentity `nitdoc_url` fun tpl_link: TplLink do var tpl = new TplLink(nitdoc_url, nitdoc_name) + var mdoc = mdoc_or_fallback if mdoc != null then tpl.title = mdoc.short_comment end @@ -75,6 +72,7 @@ redef class MEntity # A template article that briefly describe the entity fun tpl_short_article: TplArticle do var tpl = tpl_article + var mdoc = mdoc_or_fallback if mdoc != null then tpl.content = mdoc.tpl_short_comment end @@ -105,9 +103,10 @@ redef class MEntity var lnk = new Template lnk.add new TplLabel.with_classes(tpl_css_classes) lnk.add tpl_link + var mdoc = mdoc_or_fallback 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 @@ -135,26 +134,19 @@ redef class MConcern private fun tpl_concern_item: TplListItem do var lnk = new Template lnk.add tpl_anchor + var mdoc = mdoc_or_fallback 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 end redef class MProject - redef fun nitdoc_name do return name.html_escape - redef fun nitdoc_id do return nitdoc_name + redef var nitdoc_id = name.to_cmangle is lazy redef fun nitdoc_url do return root.nitdoc_url - redef fun mdoc do - if root != null then - return root.mdoc - end - return super - end - redef fun tpl_declaration do var tpl = new Template tpl.add "project " @@ -167,6 +159,7 @@ redef class MProject redef fun tpl_definition do var tpl = new TplDefinition + var mdoc = mdoc_or_fallback if mdoc != null then tpl.comment = mdoc.tpl_comment end @@ -177,25 +170,19 @@ redef class MProject end redef class MGroup - redef fun nitdoc_name do return name.html_escape - - redef fun nitdoc_id do + redef var nitdoc_id is lazy do if parent != null then - return "{parent.nitdoc_id}__{nitdoc_name}" + return "{parent.nitdoc_id}__{name.to_cmangle}" end - return "{mproject.nitdoc_id}__{nitdoc_name}" + return name.to_cmangle end redef fun nitdoc_url do return "group_{nitdoc_id}.html" redef fun tpl_namespace do var tpl = new Template - if mproject != null then - tpl.add mproject.tpl_namespace - else if parent != null then - tpl.add parent.tpl_namespace - end - if mproject != null and mproject.root != self then + tpl.add mproject.tpl_namespace + if mproject.root != self then tpl.add "::" tpl.add tpl_link end @@ -212,6 +199,7 @@ redef class MGroup redef fun tpl_definition do var tpl = new TplDefinition + var mdoc = mdoc_or_fallback if mdoc != null then tpl.comment = mdoc.tpl_comment end @@ -220,13 +208,15 @@ redef class MGroup end redef class MModule - redef fun nitdoc_name do return name.html_escape - - redef fun nitdoc_id do + redef var nitdoc_id is lazy do if mgroup != null then - return "{mgroup.nitdoc_id}__{nitdoc_name}" + if mgroup.mmodules.length == 1 then + return "{mgroup.nitdoc_id}-" + else + return "{mgroup.nitdoc_id}__{name.to_cmangle}" + end end - return nitdoc_name + return name.to_cmangle end redef fun nitdoc_url do return "module_{nitdoc_id}.html" @@ -234,7 +224,7 @@ redef class MModule redef fun tpl_declaration do var tpl = new Template tpl.add "module " - tpl.add tpl_link + tpl.add tpl_namespace tpl.add "" return tpl end @@ -251,6 +241,7 @@ redef class MModule redef fun tpl_definition do var tpl = new TplClassDefinition + var mdoc = mdoc_or_fallback if mdoc != null then tpl.comment = mdoc.tpl_comment end @@ -261,10 +252,9 @@ redef class MModule 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 var nitdoc_id = "{intro_mmodule.nitdoc_id}__{name.to_cmangle}" is lazy redef fun nitdoc_url do return "class_{nitdoc_id}.html" - redef fun mdoc do return intro.mdoc + redef fun mdoc_or_fallback do return intro.mdoc redef fun tpl_declaration do return intro.tpl_declaration @@ -293,7 +283,7 @@ redef class MClass tpl.add "[" var parameter_names = new Array[String] for p in mparameters do - parameter_names.add(p.name) + parameter_names.add(p.nitdoc_name) end tpl.add parameter_names.join(", ") tpl.add "]" @@ -312,9 +302,11 @@ end redef class MClassDef redef fun nitdoc_name do return mclass.nitdoc_name - redef fun nitdoc_id do return "{mmodule.nitdoc_id}__{name.to_cmangle}" + redef var nitdoc_id = "{mmodule.nitdoc_id}__{name.to_cmangle}" is lazy redef fun nitdoc_url do return "{mclass.nitdoc_url}#{nitdoc_id}" + redef fun mdoc_or_fallback do return mdoc or else mclass.mdoc_or_fallback + redef fun tpl_namespace do var tpl = new Template tpl.add mmodule.tpl_namespace @@ -333,6 +325,7 @@ redef class MClassDef title.add "in " title.add mmodule.tpl_namespace tpl.subtitle = title + var mdoc = mdoc_or_fallback if mdoc != null then tpl.content = mdoc.tpl_comment end @@ -361,7 +354,7 @@ redef class MClassDef if not mparameters.is_empty then tpl.add "[" for i in [0..mparameters.length[ do - tpl.add "{mparameters[i].name}: " + tpl.add "{mparameters[i].nitdoc_name}: " tpl.add bound_mtype.arguments[i].tpl_signature if i < mparameters.length - 1 then tpl.add ", " end @@ -373,6 +366,7 @@ redef class MClassDef redef fun tpl_definition do var tpl = new TplClassDefinition tpl.namespace = tpl_namespace + var mdoc = mdoc_or_fallback if mdoc != null then tpl.comment = mdoc.tpl_comment end @@ -382,8 +376,8 @@ redef class MClassDef redef fun tpl_css_classes do var set = new HashSet[String] if is_intro then set.add "intro" - set.add_all mclass.intro.modifiers - set.add_all modifiers + for m in mclass.intro.modifiers do set.add m.to_cmangle + for m in modifiers do set.add m.to_cmangle return set.to_a end @@ -391,52 +385,17 @@ redef class MClassDef var tpl = new Template for modifier in modifiers do if modifier == "public" then continue - tpl.add "{modifier} " - end - return tpl - end - - redef fun tpl_list_item do - var lnk = new Template - lnk.add new TplLabel.with_classes(tpl_css_classes) - lnk.add tpl_link - if mdoc != null then - lnk.add ": " - lnk.add mdoc.short_markdown - else if mclass.intro.mdoc != null then - lnk.add ": " - lnk.add mclass.intro.mdoc.short_markdown - end - return new TplListItem.with_content(lnk) - end - - redef fun tpl_anchor: TplLink do - var tpl = new TplLink("#{nitdoc_id}", nitdoc_name) - if mdoc != null then - tpl.title = mdoc.short_comment - else if mclass.intro.mdoc != null then - tpl.title = mclass.intro.mdoc.short_comment - end - return tpl - end - - redef fun tpl_link: TplLink do - var tpl = new TplLink(nitdoc_url, nitdoc_name) - if mdoc != null then - tpl.title = mdoc.short_comment - else if mclass.intro.mdoc != null then - tpl.title = mclass.intro.mdoc.short_comment + tpl.add "{modifier.html_escape} " end return tpl end end redef class MProperty - redef fun nitdoc_name do return name.html_escape - redef fun nitdoc_id do return "{intro_mclassdef.mclass.nitdoc_id}__{name.to_cmangle}" + redef var nitdoc_id = "{intro_mclassdef.mclass.nitdoc_id}__{name.to_cmangle}" is lazy redef fun nitdoc_url do return "property_{nitdoc_id}.html" - redef fun mdoc do return intro.mdoc + redef fun mdoc_or_fallback do return intro.mdoc redef fun tpl_namespace do var tpl = new Template @@ -460,28 +419,10 @@ end redef class MPropDef redef fun nitdoc_name do return mproperty.nitdoc_name - redef fun nitdoc_id do return "{mclassdef.nitdoc_id}__{name.to_cmangle}" + redef var nitdoc_id = "{mclassdef.nitdoc_id}__{name.to_cmangle}" is lazy redef fun nitdoc_url do return "{mproperty.nitdoc_url}#{nitdoc_id}" - redef fun tpl_anchor: TplLink do - var tpl = new TplLink("#{nitdoc_id}", nitdoc_name) - if mdoc != null then - tpl.title = mdoc.short_comment - else if mproperty.intro.mdoc != null then - tpl.title = mproperty.intro.mdoc.short_comment - end - return tpl - end - - redef fun tpl_link: TplLink do - var tpl = new TplLink(nitdoc_url, nitdoc_name) - if mdoc != null then - tpl.title = mdoc.short_comment - else if mproperty.intro.mdoc != null then - tpl.title = mproperty.intro.mdoc.short_comment - end - return tpl - end + redef fun mdoc_or_fallback do return mdoc or else mproperty.mdoc_or_fallback redef fun tpl_namespace do var tpl = new Template @@ -499,6 +440,7 @@ redef class MPropDef title.add mclassdef.tpl_link tpl.title = title tpl.subtitle = tpl_declaration + var mdoc = mdoc_or_fallback if mdoc != null then tpl.content = mdoc.tpl_comment end @@ -508,6 +450,7 @@ redef class MPropDef redef fun tpl_definition do var tpl = new TplDefinition tpl.namespace = mclassdef.tpl_namespace + var mdoc = mdoc_or_fallback if mdoc != null then tpl.comment = mdoc.tpl_comment end @@ -525,8 +468,8 @@ redef class MPropDef redef fun tpl_css_classes do var set = new HashSet[String] if is_intro then set.add "intro" - set.add_all mproperty.intro.modifiers - set.add_all modifiers + for m in mproperty.intro.modifiers do set.add m.to_cmangle + for m in modifiers do set.add m.to_cmangle return set.to_a end @@ -534,7 +477,7 @@ redef class MPropDef var tpl = new Template for modifier in modifiers do if modifier == "public" then continue - tpl.add "{modifier} " + tpl.add "{modifier.html_escape} " end return tpl end @@ -547,12 +490,10 @@ redef class MPropDef var anchor = tpl_link anchor.href = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}" lnk.add anchor + var mdoc = mdoc_or_fallback if mdoc != null then lnk.add ": " - lnk.add mdoc.short_markdown - else if mproperty.intro.mdoc != null then - lnk.add ": " - lnk.add mproperty.intro.mdoc.short_markdown + lnk.add mdoc.tpl_short_comment end return new TplListItem.with_content(lnk) end @@ -565,9 +506,10 @@ redef class MPropDef var anchor = mclassdef.tpl_link anchor.href = "{mclassdef.mclass.nitdoc_url}#{mproperty.nitdoc_id}" lnk.add anchor + var mdoc = mdoc_or_fallback 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" @@ -575,12 +517,23 @@ 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 var params = new Array[String] for param in intro.msignature.mparameters do - params.add param.name + params.add param.name.html_escape end if not params.is_empty then tpl.add "(" @@ -643,7 +596,7 @@ end redef class MParameterType redef fun tpl_link do - return new TplLink.with_title("{mclass.nitdoc_url}#FT_{name}", name, "formal type") + return new TplLink.with_title("{mclass.nitdoc_url}#FT_{name.to_cmangle}", name, "formal type") end redef fun tpl_signature do return tpl_link end @@ -718,3 +671,45 @@ redef class ConcernsTree li.append lst end end + + +################################################################################ +# Additions to `model_ext`. + +redef class MRawType + redef fun tpl_signature do + var tpl = new Template + + for part in parts do + if part.target != null then + tpl.add part.target.as(not null).tpl_link + else + tpl.add part.text.html_escape + end + end + 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 + var mdoc = mdoc_or_fallback + if mdoc != null then + tpl.comment = mdoc.tpl_comment + end + return tpl + end +end