From: Alexandre Terrasa Date: Wed, 4 Feb 2015 19:53:31 +0000 (+0100) Subject: nitdoc: introduce ExtractionPhase X-Git-Tag: v0.7.2~30^2~11 X-Git-Url: http://nitlanguage.org nitdoc: introduce ExtractionPhase Signed-off-by: Alexandre Terrasa --- diff --git a/src/doc/doc_pages.nit b/src/doc/doc_pages.nit index b0d4405..604b415 100644 --- a/src/doc/doc_pages.nit +++ b/src/doc/doc_pages.nit @@ -24,10 +24,7 @@ redef class ToolContext private var opt_source = new OptionString("link for source (%f for filename, %l for first line, %L for last line)", "--source") private var opt_sharedir = new OptionString("directory containing nitdoc assets", "--sharedir") private var opt_shareurl = new OptionString("use shareurl instead of copy shared files", "--shareurl") - private var opt_no_attributes = new OptionBool("ignore the attributes", - "--no-attributes") private var opt_nodot = new OptionBool("do not generate graphes with graphviz", "--no-dot") - private var opt_private = new OptionBool("also generate private API", "--private") private var opt_custom_title = new OptionString("custom title for homepage", "--custom-title") private var opt_custom_brand = new OptionString("custom link to external site", "--custom-brand") @@ -49,7 +46,7 @@ redef class ToolContext var opts = option_context opts.add_option(opt_dir, opt_source, opt_sharedir, opt_shareurl, - opt_no_attributes, opt_nodot, opt_private) + opt_nodot) opts.add_option(opt_custom_title, opt_custom_footer, opt_custom_intro, opt_custom_brand) opts.add_option(opt_github_upstream, opt_github_base_sha1, opt_github_gitdir) opts.add_option(opt_piwik_tracker, opt_piwik_site_id) @@ -64,12 +61,6 @@ redef class ToolContext output_dir = "doc" end self.output_dir = output_dir - # min visibility - if opt_private.value then - min_visibility = none_visibility - else - min_visibility = protected_visibility - end # github urls var gh_upstream = opt_github_upstream.value var gh_base_sha = opt_github_base_sha1.value @@ -81,23 +72,6 @@ redef class ToolContext end end end - - # Filter the entity based on the options specified by the user. - # - # Return `true` if the specified entity has to be included in the generated - # documentation - private fun filter_mclass(mclass: MClass): Bool do - return mclass.visibility >= min_visibility - end - - # Filter the entity based on the options specified by the user. - # - # Return `true` if the specified entity has to be included in the generated - # documentation - private fun filter_mproperty(mproperty: MProperty): Bool do - return mproperty.visibility >= min_visibility and - not (opt_no_attributes.value and mproperty isa MAttribute) - end end # The Nitdoc class explores the model and generate pages for each mentities found diff --git a/src/doc/doc_phases/doc_extract.nit b/src/doc/doc_phases/doc_extract.nit new file mode 100644 index 0000000..53adeac --- /dev/null +++ b/src/doc/doc_phases/doc_extract.nit @@ -0,0 +1,149 @@ +# This file is part of NIT ( http://www.nitlanguage.org ). +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +# Extract data mentities of Model that will be documented. +# +# ExtractionPhase populates the DocModel that is the base for all other phases. +# No DocPages are created at this level. +# +# TODO build a model instead? +module doc_extract + +import doc_base + +redef class ToolContext + + # Do not generate documentation for attributes. + var opt_no_attributes = new OptionBool("ignore the attributes", "--no-attributes") + + # Do not generate documentation for private properties. + var opt_private = new OptionBool("also generate private API", "--private") + + redef init do + super + option_context.add_option(opt_no_attributes, opt_private) + end + + # Minimum visibility displayed. + # + # See `opt_private`. + var min_visibility: MVisibility is lazy do + if opt_private.value then return none_visibility + return protected_visibility + end +end + +# ExtractionPhase populates the DocModel. +class ExtractionPhase + super DocPhase + + private var new_model: Model is noinit + + # Populates the given DocModel. + redef fun apply do + doc.populate(self) + end + + # Should we exclude this `mproject` from the documentation? + fun ignore_mentity(mentity: MEntity): Bool do + if mentity isa MModule then + return mentity.is_fictive or mentity.is_test_suite + else if mentity isa MClass then + return mentity.visibility < ctx.min_visibility + else if mentity isa MClassDef then + return ignore_mentity(mentity.mclass) + else if mentity isa MProperty then + return ignore_mentity(mentity.intro_mclassdef) or + mentity.visibility < ctx.min_visibility or + (ctx.opt_no_attributes.value and mentity isa MAttribute) or + mentity isa MInnerClass + else if mentity isa MPropDef then + return ignore_mentity(mentity.mclassdef) or + ignore_mentity(mentity.mproperty) + end + return false + end +end + +# TODO Should I rebuild a new Model from filtered data? +redef class DocModel + + # MProjects that will be documented. + var mprojects = new HashSet[MProject] + + # MGroups that will be documented. + var mgroups = new HashSet[MGroup] + + # MModules that will be documented. + var mmodules = new HashSet[MModule] + + # MClasses that will be documented. + var mclasses = new HashSet[MClass] + + # MClassDefs that will be documented. + var mclassdefs = new HashSet[MClassDef] + + # MProperties that will be documented. + var mproperties = new HashSet[MProperty] + + # MPropdefs that will be documented. + var mpropdefs = new HashSet[MPropDef] + + # Populate `self` from internal `model`. + fun populate(v: ExtractionPhase) do + populate_mprojects(v) + populate_mclasses(v) + populate_mproperties(v) + end + + # Populates the `mprojects` set. + private fun populate_mprojects(v: ExtractionPhase) do + for mproject in model.mprojects do + if v.ignore_mentity(mproject) then continue + self.mprojects.add mproject + for mgroup in mproject.mgroups do + if v.ignore_mentity(mgroup) then continue + self.mgroups.add mgroup + for mmodule in mgroup.mmodules do + if v.ignore_mentity(mmodule) then continue + self.mmodules.add mmodule + end + end + end + end + + # Populates the `mclasses` set. + private fun populate_mclasses(v: ExtractionPhase) do + for mclass in model.mclasses do + if v.ignore_mentity(mclass) then continue + self.mclasses.add mclass + for mclassdef in mclass.mclassdefs do + if v.ignore_mentity(mclassdef) then continue + self.mclassdefs.add mclassdef + end + end + end + + # Populates the `mproperties` set. + private fun populate_mproperties(v: ExtractionPhase) do + for mproperty in model.mproperties do + if v.ignore_mentity(mproperty) then continue + self.mproperties.add mproperty + for mpropdef in mproperty.mpropdefs do + if v.ignore_mentity(mpropdef) then continue + self.mpropdefs.add mpropdef + end + end + end +end diff --git a/src/doc/doc_phases/doc_phases.nit b/src/doc/doc_phases/doc_phases.nit index 568c0b8..00d746e 100644 --- a/src/doc/doc_phases/doc_phases.nit +++ b/src/doc/doc_phases/doc_phases.nit @@ -16,3 +16,5 @@ # # See `DocPhase`. module doc_phases + +import doc_extract diff --git a/src/nitdoc.nit b/src/nitdoc.nit index d267544..b9175ed 100644 --- a/src/nitdoc.nit +++ b/src/nitdoc.nit @@ -32,7 +32,7 @@ private class Nitdoc do var doc = new DocModel(mainmodule.model, mainmodule) - var phases = new Array[DocPhase] + var phases = [new ExtractionPhase(toolcontext, doc)] for phase in phases do toolcontext.info("# {phase.class_name}", 1)