From: Jean Privat <jean@pryen.org>
Date: Tue, 18 Aug 2015 12:47:14 +0000 (-0400)
Subject: loader: document ` identify_file`
X-Git-Tag: v0.7.8~81^2
X-Git-Url: http://nitlanguage.org

loader: document ` identify_file`

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

diff --git a/src/loader.nit b/src/loader.nit
index f9f9cf7..7d1c564 100644
--- a/src/loader.nit
+++ b/src/loader.nit
@@ -344,10 +344,18 @@ redef class ModelBuilder
 	# See `identify_file`.
 	var identified_files = new Array[ModulePath]
 
-	# Identify a source file
-	# Load the associated project and groups if required
+	# Identify a source file and load the associated project and groups if required.
 	#
-	# Silently return `null` if `path` is not a valid module path.
+	# This method does what the user expects when giving an argument to a Nit tool.
+	#
+	# * If `path` is an existing Nit source file (with the `.nit` extension),
+	#   then the associated ModulePath is returned
+	# * If `path` is a directory (with a `/`),
+	#   then the ModulePath of its default module is returned (if any)
+	# * If `path` is a simple identifier (eg. `digraph`),
+	#   then the main module of the project `digraph` is searched in `paths` and returned.
+	#
+	# Silently return `null` if `path` does not exists or cannot be identified.
 	fun identify_file(path: String): nullable ModulePath
 	do
 		# special case for not a nit file