-# The main module of the nitdoc program
-package nitdoc
-
-import syntax
-private import utils
-import abstracttool
-
-
-# Store knowledge and facilities to generate files
-class DocContext
-special AbstractCompiler
- # Destination directory
- readable writable var _dir: String = "."
-
- # Content of a generated file
- var _stage_context: StageContext = new StageContext(null)
-
- # Add a string in the content
- fun add(s: String) do
- _stage_context.content.add(s)
- _stage_context.validate = true
- end
-
- # Add a string in the content iff some other string are added
- fun stage(s: String) do _stage_context.content.add(s)
-
- # Create a new stage in the content
- fun open_stage do _stage_context = new StageContext(_stage_context)
-
- # Close the current stage in the content
- fun close_stage
- do
- var s = _stage_context.parent
- if _stage_context.validate then
- s.content.add_all(_stage_context.content)
- s.validate = true
- end
- assert s != null
- _stage_context = s
- end
-
- # Write the content to a new file
- fun write_to(filename: String)
- do
- var f = new OFStream.open(filename)
- for s in _stage_context.content do
- f.write(s)
- end
- f.close
- end
-
- # Currently computed module
- readable var _module: nullable MMSrcModule
-
- # Is the current directory module computed as a simple modude ?
- readable writable var _inside_mode: Bool = false
-
- # Is the current module computed as a intruded one ?
- readable writable var _intrude_mode: Bool = false
-
- # Compued introducing entities (for the index)
- var _entities: Array[MMEntity] = new Array[MMEntity]
-
- # Register an entity (for the index)
- fun register(e: MMEntity)
- do
- _entities.add(e)
- if e isa MMSrcModule then
- _module = e
- end
- end
-
- # Start a new file
- fun clear
- do
- _stage_context = new StageContext(null)
- end
-
- # Generate common files (frames, index, overview)
- fun extract_other_doc
- do
- info("Generating other files",1)
- _module = null
- inside_mode = false
- intrude_mode = false
- clear
- add("<html><body>\n")
- add("<a href=\"overview.html\" target=\"mainFrame\">Overview</a><br/>\n")
- add("<a href=\"index-1.html\" target=\"mainFrame\">Index</a><br/>\n")
- var modules = modules.to_a
- sort(modules)
-
- var rootdirs = new Array[MMDirectory]
- for m in modules do
- var md = m.directory
- if md.parent == null and not rootdirs.has(md) then
- rootdirs.add(md)
- end
- end
-
- var done = new Array[MMModule]
- for root in rootdirs do
- var dirstack = [root]
- var curdir = root
- add("{root.name}<br/>\n")
- var indent = " "
- while not dirstack.is_empty do
- var redo = false
- for m in modules do
- if done.has(m) then continue
- var md = m.directory
- if md.owner == m and md.parent == curdir then
- # It's a directory module
- add("{indent}<a href=\"{m}.html\" target=\"mainFrame\">{m}</a><br/>\n")
- curdir = md
- dirstack.push(curdir)
- indent = "  " * dirstack.length
- redo = true
- break # restart to preserve alphabetic order
- else if md == curdir then
- if md.owner == m then
- add("{indent}<a href=\"{m}_.html\" target=\"mainFrame\">{m}</a><br/>\n")
- else
- add("{indent}<a href=\"{m}.html\" target=\"mainFrame\">{m}</a><br/>\n")
- end
- done.add(m)
- redo = true
- end
- end
- if not redo then
- dirstack.pop
- if not dirstack.is_empty then
- curdir = dirstack[dirstack.length-1]
- indent = "  " * dirstack.length
- end
- end
- end
- end
- add("</body></html>\n")
- write_to("{dir}/menu-frame.html")
-
- clear
- add_header("Index")
- add("<dl>\n")
- sort(_entities)
- for e in _entities do
- add("<dt><b>{e.html_link(self)}</b> - {e.prototype_head(self)} <b>{e}</b>{e.prototype_body(self)} {e.locate(self)}<dd>{e.short_doc}\n")
- end
- add("</dl></body></html>\n")
- write_to("{dir}/index-1.html")
-
- clear
- add_header("Overview")
- add("<table border=\"1\" width=\"100%\" cellpadding=\"3\" cellspacing=\"0\">\n")
- add("<tr bgcolor=\"#CCCCFF\"><th colspan=\"2\"><big>Overview of all Modules</big></th><tr>\n")
- for m in modules do
- add("<tr><td width=\"20%\" align=\"right\">{m.html_link(self)}</td><td>{m.short_doc}</td><tr>\n")
- end
- add("</table></body></html>\n")
- write_to("{dir}/overview.html")
-
- clear
- add("<html>\n<frameset cols=\"20%,80%\">\n<frame src=\"menu-frame.html\" name=\"menuFrame\" title=\"Menu\">\n<frame src=\"overview.html\" name=\"mainFrame\" title=\"Main\" scrolling=\"yes\">\n</frameset></html>\n")
- write_to("{dir}/index.html")
- end
-
- fun add_header(title: String)
- do
- add("<html><head><title>{title}</title></head>\n<body>\n")
- add("<table border=\"0\" width=\"100%\" cellpadding=\"1\" cellspacing=\"0\"><tr><td bgcolor=\"#eeeeff\">\n")
- add("<a href=\"overview.html\"><b>Overview</b></a> <a href=\"index-1.html\"><b>Index</b></a> <a href=\"index.html\" target=\"_top\"><b>With Frames</b></a>\n")
- add("</td></tr></table>")
- add("Visibility: ")
- var module = module
- if (not inside_mode and not intrude_mode) or module == null then
- add("<b>Public</b> ")
- else
- add("<a href=\"{module}.html\"><b>Public</b></a> ")
- end
- if inside_mode or module == null then
- add("<b>Inside</b> ")
- else if module.directory.owner != module then
- add("<strike><b>Inside</b></strike> ")
- else
- add("<a href=\"{module}_.html\"><b>Inside</b></a> ")
- end
- if intrude_mode or module == null then
- add("<b>Intrude</b> ")
- else
- add("<a href=\"{module}__.html\"><b>Intrude</b></a> ")
- end
- add("<br/>")
- end
-
- # Sorter of entities in alphabetical order
- var _sorter: AlphaSorter[MMEntity] = new AlphaSorter[MMEntity]
-
- # Sort entities in the alphabetical order
- fun sort(array: Array[MMEntity])
- do
- _sorter.sort(array)
- end
-
- readable writable var _owned_modules: Array[MMModule] = new Array[MMModule]
-
- # Return the known_owner for current module
- # if inside_mode is set, it could be a different result
- fun known_owner_of(m: MMModule): MMModule
- do
- var module = module
- if module == null then return m
- var res = module.known_owner_of(m)
- if not inside_mode and not intrude_mode and res.directory.owner == module then
- return module
- else
- return res
- end
- end
-
- readable var _opt_dir: OptionString = new OptionString("Directory where doc is generated", "-d", "--dir")
-
- redef fun perform_work(mods)
- do
- dir.mkdir
-
- for mod in modules do
- assert mod isa MMSrcModule
- mod.extract_module_doc(self)
- end
- self.extract_other_doc
- end
-
- init
- do
- keep_ast = true
- super("nitdoc")
- option_context.add_option(opt_dir)
- end
-
- redef fun process_options
- do
- super
- var d = opt_dir.value
- if d != null then dir = d
- end
-end
-
-# Conditionnal part of the text content of a DocContext
-class StageContext
- # Content of the current stage
- readable var _content: Array[String] = new Array[String]
-
- # Is a normal string already added?
- readable writable var _validate: Bool = false
-
- # Parent stage is any
- readable var _parent: nullable StageContext = null
-
- init(parent: nullable StageContext) do _parent = parent
-end
-
-
-# Efficiently sort object with their to_s method
-class AlphaSorter[E: Object]
-special AbstractSorter[E]
- redef fun compare(a, b)
- do
- var sa: String
- var sb: String
- var d = _dico
- if d.has_key(a) then
- sa = d[a]
- else
- sa = a.to_s
- d[a] = sa
- end
- if d.has_key(b) then
- sb = d[b]
- else
- sb = b.to_s
- d[b] = sb
- end
- return sa <=> sb
- end
-
- # Keep track of to_s values
- var _dico: HashMap[Object, String] = new HashMap[Object, String]
-
- init do end
-end
-
-# Generalization of metamodel entities
-class MMEntity
- # Return a link to
- fun html_link(dctx: DocContext): String is abstract
-
- # Is the entity should appear in the generaed doc
- fun need_doc(dctx: DocContext): Bool is abstract
-
- # Return a one liner description
- fun short_doc: String do return " "
-
- # The doc node from the AST
- # Return null is none
- fun doc: nullable ADoc do return null
-
- # Human redable location of the entity (module/class/property)
- fun locate(dctx: DocContext): String do return ""
-
- # Part of the prototype before the name (kind, modifiers, qualifier)
- fun prototype_head(dctx: DocContext): String is abstract
-
- # Part of the property after the name (signature, modifiers)
- fun prototype_body(dctx: DocContext): String do return ""
-end
-
-redef class MMModule
-special MMEntity
- redef fun html_link(dctx) do
- if dctx.module == self then
- return "{self}"
- else
- return "<a href=\"{self}.html\">{self}</a>"
- end
- end
- redef fun need_doc(dctx) do return true
- redef fun prototype_head(dctx) do return "module "
-
- var _known_owner_of_cache: Map[MMModule, MMModule] = new HashMap[MMModule, MMModule]
-
- # Return the owner of `module` from the point of view of `self`
- fun known_owner_of(module: MMModule): MMModule
- do
- if _known_owner_of_cache.has_key(module) then return _known_owner_of_cache[module]
- var res = module
- # is module is publicly imported by self?
- if mhe < module and visibility_for(module) != 0 then
- res = known_owner_of_intern(module, self, false)
- else
- # Return the canonnical owner of module from the point of view of self
- res = module.owner(self)
- end
- _known_owner_of_cache[module] = res
- return res
- end
-
- # Return the most general module that own self
- fun owner(from: MMModule): MMModule
- do
- var res = self
- var d: nullable MMDirectory = directory
- while d != null and d != from.directory do
- var o = d.owner
- if o != null and o.mhe <= res then res = o
- d = d.parent
- end
- return res
- end
-
- # ???
- private fun known_owner_of_intern(module: MMModule, from: MMModule, as_owner: Bool): MMModule
- do
- if module == self then return self
- var candidates = new Array[MMModule]
- for m in explicit_imported_modules do
- if from.visibility_for(m) == 0 then continue
- if not m.mhe <= module then continue
- candidates.add(m.known_owner_of_intern(module, from, true))
- end
- # FIXME: I do not know what this does
- if candidates.is_empty then return module.owner(from)
- var max = candidates.first
- for m in candidates do
- if max.mhe < m then max = m
- end
- if as_owner and max.directory.owner == self then
- return self
- else
- return max
- end
- end
-
-end
-
-redef class MMLocalProperty
-special MMEntity
- # Anchor of the property description in the module html file
- fun html_anchor: String
- do
- return "PROP_{local_class}_{cmangle(name)}"
- end
-
- redef fun html_link(dctx)
- do
- var m = module
- if not need_doc(dctx) then m = global.intro.module
- m = dctx.known_owner_of(m)
- if m == dctx.module then
- return "<a href=\"#{html_anchor}\">{self}</a>"
- else
- return "<a href=\"{m}.html#{html_anchor}\">{self}</a>"
- end
- end
-
- # Kind of property (fun, attr, etc.)
- fun kind: String is abstract
-
- redef fun locate(dctx)
- do
- return "in {module.html_link(dctx)}::{local_class.html_link(dctx)}"
- end
-
- fun known_intro_class(dctx: DocContext): MMLocalClass
- do
- var mod = dctx.known_owner_of(global.intro.local_class.module)
- var cla = mod[global.intro.local_class.global]
- return cla
- end
-
- redef fun prototype_head(dctx)
- do
- var res = new Buffer
- var intro_class = known_intro_class(dctx)
- var is_redef = local_class != intro_class
-
- if is_redef then res.append("redef ")
- if global.visibility_level == 2 then
- res.append("protected ")
- else if global.visibility_level == 3 then
- res.append("private ")
- end
- res.append(kind)
- if is_redef then
- var gp = global.intro
- if intro_class.global != local_class.global then
- res.append(" {module[intro_class.global].html_link(dctx)}::")
- else if intro_class.module != module then
- res.append(" {intro_class.module.html_link(dctx)}::")
- end
- end
- return res.to_s
- end