[ticket/10933] Prose for get_first_file_location.

Also rewrite get_first_template_location prose a little to be
less repetitive with get_first_file_location.

PHPBB3-10933

phpBB/includes/style/resource_locator.php

@@ -295,19 +295,26 @@ class phpbb_style_resource_locator implements phpbb_template_locator
 	* each template in the array to a path, and will return the first
 	* path that exists, or false if none exist.
 	*
+	* If $files is an array and template inheritance is involved, first
+	* each of the files will be checked in the selected style, then each
+	* of the files will be checked in the immediate parent, and so on.
+	*
 	* If $return_full_path is false, then instead of returning a usable
 	* path (when the template is found) only the template's basename
 	* will be returned. This can be used to check which of the templates
-	* specified in $files exists, provided different file names are
+	* specified in $files exists. Naturally more than one template must
-	* used for different templates.
+	* be given in $files.
 	*
-	* Just like get_first_file_location but works on a list of templates,
+	* This function works identically to get_first_file_location except
-	* not files.
+	* it operates on a list of templates, not files. Practically speaking,
-	*
+	* the templates given in the first argument first are prepended with
-	* The templates given in the first argument first are prepended with
 	* the template path (property in this class), then given to
 	* get_first_file_location for the rest of the processing.
 	*
+	* Templates given to this function can be relative paths for templates
+	* located in subdirectories of the template directories. The paths
+	* should be relative to the templates directory (template/ by default).
+	*
 	* @param string or array $files List of templates to locate. If there is only
 	*				one template, $files can be a string to make code easier to read.
 	* @param bool $return_default Determines what to return if template does not

phpBB/includes/template/locator.php

@@ -99,12 +99,54 @@ interface phpbb_template_locator
 	public function get_source_file_for_handle($handle, $find_all = false);
 
 	/**
-	* Locates source file path, accounting for styles tree and verifying that
+	* Obtains a complete filesystem path for a file in a style.
-	* the path exists.
 	*
-	* Unlike previous functions, this function works without template handle
+	* This function traverses the style tree (selected style and
-	* and it can search for more than one file. If more than one file name is
+	* its parents in order, if inheritance is being used) and finds
-	* specified, it will return location of file that it finds first.
+	* the first file on the filesystem matching specified relative path,
+	* or the first of the specified paths if more than one path is given.
+	*
+	* This function can be used to determine filesystem path of any
+	* file under any style, with the consequence being that complete
+	* relative to the style directory path must be provided as an argument.
+	*
+	* In particular, this function can be used to locate templates
+	* and javascript files.
+	*
+	* For locating templates get_first_template_location should be used
+	* as it prepends the configured template path to the template basename.
+	*
+	* Note: "selected style" is whatever style the style resource locator
+	* is configured for.
+	*
+	* The return value then will be a path, relative to the current
+	* directory or absolute, to the first existing file in the selected
+	* style or its closest parent.
+	*
+	* If the selected style does not have the file being searched,
+	* (and if inheritance is involved, none of the parents have it either),
+	* false will be returned.
+	*
+	* Multiple files can be specified, in which case the first file in
+	* the list that can be found on the filesystem is returned.
+	*
+	* If multiple files are specified and inheritance is involved,
+	* first each of the specified files is checked in the selected style,
+	* then each of the specified files is checked in the immediate parent,
+	* etc.
+	*
+	* Specifying true for $return_default will cause the function to
+	* return the first path which was checked for existence in the event
+	* that the template file was not found, instead of false.
+	* This is always a path in the selected style itself, not any of its
+	* parents.
+	*
+	* If $return_full_path is false, then instead of returning a usable
+	* path (when the file is found) the file's path relative to the style
+	* directory will be returned. This is the same path as was given to
+	* the function as a parameter. This can be used to check which of the
+	* files specified in $files exists. Naturally this requires passing
+	* more than one file in $files.
 	*
 	* @param array $files List of files to locate.
 	* @param bool $return_default Determines what to return if file does not