From 88a222fff30276c50ebef3859bece6810f1509f4 Mon Sep 17 00:00:00 2001
From: Russell Michell <russell@silverstripe.com>
Date: Fri, 18 May 2012 12:32:12 +1200
Subject: [PATCH] MINOR: Updated inline phpdoc while investigating trac/4113

---
 i18n/i18nTextCollector.php | 39 ++++++++++++++++++++++++++++++--------
 1 file changed, 31 insertions(+), 8 deletions(-)

diff --git a/i18n/i18nTextCollector.php b/i18n/i18nTextCollector.php
index 6879d2fc98d..b80d5d1f945 100644
--- a/i18n/i18nTextCollector.php
+++ b/i18n/i18nTextCollector.php
@@ -152,9 +152,12 @@ public function run($restrictToModules = null) {
 	}
 	
 	/**
-	 * Build the module's master string table
+	 * Builds a master string table from php and .ss template files for the module passed as the $module param
+	 * @see {@link collectFromCode} and {@link collectFromTemplate}
 	 *
-	 * @param string $module Module's name or 'themes'
+	 * @param string $module A module's name or just 'themes'
+	 * @return array $entities An array of entities found in the files that comprise the module
+	 * @todo Why the type juggling for $this->collectFromBlah()? They always return arrays.
 	 */
 	protected function processModule($module) {	
 		$entities = array();
@@ -194,6 +197,13 @@ protected function processModule($module) {
 		return $entities;
 	}
 
+	/**
+	 * Extracts translatables from .php files.
+	 * 
+	 * @param string $content The text content of a parsed template-file
+	 * @param string $module Module's name or 'themes'
+	 * @return array $entities An array of entities representing the extracted translation function calls in code
+	 */		
 	public function collectFromCode($content, $module) {
 		$entities = array();
 
@@ -267,6 +277,16 @@ public function collectFromCode($content, $module) {
 		return $entities;
 	}
 
+	/**
+	 * Extracts translatables from .ss templates (Self referencing)
+	 * 
+	 * @param string $content The text content of a parsed template-file
+	 * @param string $module Module's name or 'themes'
+	 * @param string $fileName The name of a template file when method is used in self-referencing mode
+	 * @return array $entities An array of entities representing the extracted template function calls
+	 * 
+	 * @todo Why the type juggling for $this->collectFromTemplate()? It always returns an array.
+	 */	
 	public function collectFromTemplate($content, $fileName, $module) {
 		$entities = array();
 		
@@ -330,9 +350,11 @@ function collectFromEntityProviders($filePath) {
 	}
 	
 	/**
-	 * @param String $fullName
-	 * @param String $_namespace 
-	 * @return String|FALSE
+	 * Normalizes enitities with namespaces.
+	 * 
+	 * @param string $fullName
+	 * @param string $_namespace 
+	 * @return string|boolean FALSE
 	 */
 	protected function normalizeEntity($fullName, $_namespace = null) {
 		// split fullname into entity parts
@@ -360,11 +382,12 @@ protected function normalizeEntity($fullName, $_namespace = null) {
 	
 	
 	/**
-	 * Helper function that searches for potential files to be parsed
+	 * Helper function that searches for potential files (templates and code) to be parsed
 	 * 
 	 * @param string $folder base directory to scan (will scan recursively)
-	 * @param array $fileList Array where potential files will be added to
-	 * @param String $type Optional, "php" or "ss"
+	 * @param array $fileList Array to which potential files will be appended
+	 * @param string $type Optional, "php" or "ss"
+	 * @return array $fileList An array of files
 	 */
 	protected function getFilesRecursive($folder, &$fileList = null, $type = null) {
 		if(!$fileList) $fileList = array();