From: Jean Privat <jean@pryen.org>
Date: Sat, 20 Dec 2014 01:20:13 +0000 (-0500)
Subject: src: finish documenting some module
X-Git-Tag: v0.7~9^2
X-Git-Url: http://nitlanguage.org?ds=sidebyside

src: finish documenting some module

Signed-off-by: Jean Privat <jean@pryen.org>
---

diff --git a/src/frontend/cached.nit b/src/frontend/cached.nit
index 4af7e46..f331b1d 100644
--- a/src/frontend/cached.nit
+++ b/src/frontend/cached.nit
@@ -14,8 +14,7 @@
 
 # Implementation of the method-related annotation `cached`
 #
-# Note this module can be used as a reference on how to implements
-# complex annotation that modify both the model and the AST of a Nit program
+# The cached annotation is deprecated, use the `lazy` annotation instead.
 module cached
 
 import modelize
@@ -25,6 +24,7 @@ private import annotation
 intrude import modelize::modelize_property
 
 redef class ToolContext
+	# Process the `cached` annotation on methods
 	var cached_phase: Phase = new CachedPhase(self, [modelize_property_phase])
 end
 
diff --git a/src/frontend/check_annotation.nit b/src/frontend/check_annotation.nit
index 7cd186e..1b9ceb7 100644
--- a/src/frontend/check_annotation.nit
+++ b/src/frontend/check_annotation.nit
@@ -22,6 +22,7 @@ import phase
 private import annotation
 
 redef class ToolContext
+	# Check for unknown annotation in each module
 	var check_annotation_phase: Phase = new CheckAnnotationPhase(self, null)
 end
 
diff --git a/src/frontend/frontend.nit b/src/frontend/frontend.nit
index 53c1a77..a7feffe 100644
--- a/src/frontend/frontend.nit
+++ b/src/frontend/frontend.nit
@@ -28,7 +28,9 @@ import glsl_validation
 redef class ToolContext
 	# FIXME: there is conflict in linex in nitc, so use this trick to force invocation
 	private var dummy: Bool = do_dummy
-	fun do_dummy: Bool
+
+	# SEE `dummy`
+	private fun do_dummy: Bool
 	do
 		# Force easy warnings after modelbuilder
 		phases.add_edge(simple_misc_analysis_phase, modelize_property_phase)
diff --git a/src/frontend/serialization_phase.nit b/src/frontend/serialization_phase.nit
index a035c8e..78c8c89 100644
--- a/src/frontend/serialization_phase.nit
+++ b/src/frontend/serialization_phase.nit
@@ -24,7 +24,10 @@ import modelize
 private import annotation
 
 redef class ToolContext
+	# Generate serialization and deserialization methods on `auto_serializable` annotated classes.
 	var serialization_phase_pre_model: Phase = new SerializationPhasePreModel(self, null)
+
+	# The second phase of the serialization
 	var serialization_phase_post_model: Phase = new SerializationPhasePostModel(self,
 		[modelize_class_phase, serialization_phase_pre_model])
 
diff --git a/src/frontend/simple_misc_analysis.nit b/src/frontend/simple_misc_analysis.nit
index c897ed9..cc12d01 100644
--- a/src/frontend/simple_misc_analysis.nit
+++ b/src/frontend/simple_misc_analysis.nit
@@ -24,6 +24,7 @@ module simple_misc_analysis
 import phase
 
 redef class ToolContext
+	# Execute `AModule::do_simple_misc_analysis` on each module.
 	var simple_misc_analysis_phase: Phase = new SimpleMiscAnalysisPhase(self, null)
 end
 
diff --git a/src/highlight.nit b/src/highlight.nit
index d70281e..ecc4c7d 100644
--- a/src/highlight.nit
+++ b/src/highlight.nit
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Highliting of Nit AST
+# Highlighting of Nit AST
 module highlight
 
 import frontend
@@ -48,6 +48,8 @@ class HighlightVisitor
 		html.add_class("nitcode")
 	end
 
+	# The entry-point of the highlighting.
+	# Will fill `html` with the generated HTML content.
 	fun enter_visit(n: ANode)
 	do
 		n.parentize_tokens
@@ -329,6 +331,7 @@ redef class MModule
 		return res
 	end
 
+	# The module HTML page
 	fun href: String
 	do
 		return name + ".html"
@@ -386,6 +389,7 @@ redef class MClassDef
 		return res
 	end
 
+	# The class HTML page (an anchor in the module page)
 	fun href: String
 	do
 		return mmodule.href + "#" + to_s
@@ -432,6 +436,7 @@ redef class MPropDef
 		return res
 	end
 
+	# The property HTML page (an anchor in the module page)
 	fun href: String
 	do
 		return self.mclassdef.mmodule.href + "#" + self.to_s
diff --git a/src/literal.nit b/src/literal.nit
index e39409f..23dcacd 100644
--- a/src/literal.nit
+++ b/src/literal.nit
@@ -20,6 +20,7 @@ module literal
 import phase
 
 redef class ToolContext
+	# Parses literal values in the whole AST and produces errors if needed
 	var literal_phase: Phase = new LiteralPhase(self, null)
 end
 
diff --git a/src/location.nit b/src/location.nit
index e82775a..d7154ca 100644
--- a/src/location.nit
+++ b/src/location.nit
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This module is used to model Nit source-file and locations in source-file
+# Nit source-file and locations in source-file
 module location
 
 # A raw text Nit source file
@@ -51,8 +51,13 @@ class Location
 	super Comparable
 	redef type OTHER: Location
 
+	# The associated source-file
 	var file: nullable SourceFile
+
+	# The starting line number (starting from 1)
 	var line_start: Int
+
+	# The stopping line number (starting from 1)
 	var line_end: Int
 
 	# Start of this location on `line_start`
@@ -64,6 +69,7 @@ class Location
 	# Require: `column_start >= 0`
 	var column_start: Int
 
+	# End of this location on `line_end`
 	var column_end: Int
 
 	# The index in the start character in the source
@@ -87,8 +93,6 @@ class Location
 
 	private var text_cache: nullable String = null
 
-	init with_file(f: SourceFile) do init(f,0,0,0,0)
-
 	redef fun ==(other: nullable Object): Bool do
 		if other == null then return false
 		if not other isa Location then return false
diff --git a/src/model/model.nit b/src/model/model.nit
index 8eabb75..4d8ddc4 100644
--- a/src/model/model.nit
+++ b/src/model/model.nit
@@ -373,6 +373,7 @@ class MClass
 	# is empty if the class is not generic
 	var mparameters = new Array[MParameterType]
 
+	# Initialize `mparameters` from their names.
 	protected fun setup_parameter_names(parameter_names: nullable Array[String]) is
 		autoinit
 	do
@@ -1693,6 +1694,8 @@ class MParameter
 		end
 	end
 
+	# Returns a new parameter with the `mtype` resolved.
+	# See `MType::resolve_for` for details.
 	fun resolve_for(mtype: MType, anchor: nullable MClassType, mmodule: MModule, cleanup_virtual: Bool): MParameter
 	do
 		if not self.mtype.need_anchor then return self
diff --git a/src/modelbuilder_base.nit b/src/modelbuilder_base.nit
index d09b717..1f8c184 100644
--- a/src/modelbuilder_base.nit
+++ b/src/modelbuilder_base.nit
@@ -234,6 +234,8 @@ end
 
 redef class ADoc
 	private var mdoc_cache: nullable MDoc
+
+	# Convert `self` to a `MDoc`
 	fun to_mdoc: MDoc
 	do
 		var res = mdoc_cache
diff --git a/src/modelize/modelize_class.nit b/src/modelize/modelize_class.nit
index ae9da02..5112e25 100644
--- a/src/modelize/modelize_class.nit
+++ b/src/modelize/modelize_class.nit
@@ -20,6 +20,7 @@ module modelize_class
 import modelbuilder
 
 redef class ToolContext
+	# Run `AModule::build_classes` on each module
 	var modelize_class_phase: Phase = new ModelizeClassPhase(self, null)
 end
 
diff --git a/src/modelize/modelize_property.nit b/src/modelize/modelize_property.nit
index fef5ca9..11fa271 100644
--- a/src/modelize/modelize_property.nit
+++ b/src/modelize/modelize_property.nit
@@ -21,6 +21,7 @@ intrude import modelize_class
 private import annotation
 
 redef class ToolContext
+	# Run `AClassdef::build_property` on the classdefs of each module
 	var modelize_property_phase: Phase = new ModelizePropertyPhase(self, [modelize_class_phase])
 end
 
@@ -324,7 +325,8 @@ redef class MPropDef
 end
 
 redef class AClassdef
-	var build_properties_is_done = false
+	# Marker used in `ModelBuilder::build_properties`
+	private var build_properties_is_done = false
 
 	# The free init (implicitely constructed by the class if required)
 	var mfree_init: nullable MMethodDef = null
diff --git a/src/parser_util.nit b/src/parser_util.nit
index 82aec57..ff06f0e 100644
--- a/src/parser_util.nit
+++ b/src/parser_util.nit
@@ -222,10 +222,15 @@ redef class ToolContext
 	end
 end
 
+# A modified lexer that feed tokens before and after the real tokens.
 class InjectedLexer
 	super Lexer
 
+	# The tokens to use before the real tokens (in order).
 	var injected_before = new List[Token]
+
+	# The tokens to use after the real tokens (in order).
+	# The real EOF token is produced after these tokens.
 	var injected_after = new List[Token]
 	private var is_finished = false
 
diff --git a/src/phase.nit b/src/phase.nit
index 2011cd8..5729313 100644
--- a/src/phase.nit
+++ b/src/phase.nit
@@ -21,7 +21,7 @@ import poset
 
 redef class ToolContext
 	# The various registered phases to performs
-	# The order in the poset is the dependance of phases
+	# The order in the poset is the dependence of phases
 	#
 	# While you can directly modify the poset (nodes and edges),
 	# it is often simpler to use the constructor in `Phase`
@@ -64,6 +64,7 @@ redef class ToolContext
 		end
 	end
 
+	# The list of registered phases in the application order.
 	fun phases_list: Sequence[Phase]
 	do
 		var phases = self.phases.to_a
@@ -136,7 +137,9 @@ redef class ToolContext
 		errors_info
 	end
 
-	fun phase_process_npropdef(phase: Phase, npropdef: APropdef)
+	# Process the given `phase` on the `npropdef`
+	# Called by `run_phases`
+	protected fun phase_process_npropdef(phase: Phase, npropdef: APropdef)
 	do
 		phase.process_npropdef(npropdef)
 	end
diff --git a/src/semantize/auto_super_init.nit b/src/semantize/auto_super_init.nit
index ac7763e..b16eaf5 100644
--- a/src/semantize/auto_super_init.nit
+++ b/src/semantize/auto_super_init.nit
@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# Computing of super-constructors that must be implicitely called at the begin of constructors.
+# Computing of super-constructors that must be implicitly called at the begin of constructors.
 # The current rules are a bit crazy but whatever.
 module auto_super_init
 
@@ -22,6 +22,7 @@ import typing
 private import annotation
 
 redef class ToolContext
+	# Phase that inject `super` in constructors that need it.
 	var auto_super_init_phase: Phase = new AutoSuperInitPhase(self, [typing_phase])
 end
 
diff --git a/src/semantize/flow.nit b/src/semantize/flow.nit
index 02ce863..1f96058 100644
--- a/src/semantize/flow.nit
+++ b/src/semantize/flow.nit
@@ -20,6 +20,7 @@ module flow
 import scope
 
 redef class ToolContext
+	# Run `APropdef::do_flow` on each propdef
 	var flow_phase: Phase = new FlowPhase(self, [scope_phase])
 end
 
diff --git a/src/semantize/local_var_init.nit b/src/semantize/local_var_init.nit
index 4b3fd52..82fa0a4 100644
--- a/src/semantize/local_var_init.nit
+++ b/src/semantize/local_var_init.nit
@@ -21,6 +21,7 @@ module local_var_init
 import flow
 
 redef class ToolContext
+	# Run `APropdef::do_local_var_init` on each propdef
 	var local_var_init_phase: Phase = new LocalVarInitPhase(self, [flow_phase])
 end
 
diff --git a/src/semantize/scope.nit b/src/semantize/scope.nit
index ad6bcd8..6b4e973 100644
--- a/src/semantize/scope.nit
+++ b/src/semantize/scope.nit
@@ -20,6 +20,7 @@ module scope
 import phase
 
 redef class ToolContext
+	# Run `APropdef::do_scope` on each propdef.
 	var scope_phase: Phase = new ScopePhase(self, null)
 end
 
diff --git a/src/testing/testing_doc.nit b/src/testing/testing_doc.nit
index 2bdbb02..f0b8102 100644
--- a/src/testing/testing_doc.nit
+++ b/src/testing/testing_doc.nit
@@ -299,28 +299,21 @@ class DocUnit
 	var block: String
 end
 
-class SearchAssertVisitor
-	super Visitor
-	var foundit = false
-	redef fun visit(node)
-	do
-		if foundit then
-			return
-		else if node isa AAssertExpr then
-			foundit = true
-			return
-		else
-			node.visit_all(self)
-		end
-	end
-end
-
 redef class ModelBuilder
+	# Total number analyzed `MEntity`
 	var total_entities = 0
+
+	# The number of `MEntity` that have some documentation
 	var doc_entities = 0
+
+	# The total number of executed docunits
 	var unit_entities = 0
+
+	# The number failed docunits
 	var failed_entities = 0
 
+	# Extracts and executes all the docunits in the `mmodule`
+	# Returns a JUnit-compatible `<testsuite>` XML element that contains the results of the executions.
 	fun test_markdown(mmodule: MModule): HTMLTag
 	do
 		var ts = new HTMLTag("testsuite")