[feature/template-engine] Remaining documentation.

PHPBB3-9726

phpBB/includes/template/compile.php

@@ -32,6 +32,11 @@ class phpbb_template_compile
 	*/
 	private $allow_php;
 
+	/**
+	* Constructor.
+	*
+	* @param bool @allow_php Whether PHP code will be allowed in templates (inline PHP code, PHP tag and INCLUDEPHP tag)
+	*/
 	public function __construct($allow_php)
 	{
 		$this->allow_php = $allow_php;
@@ -40,6 +45,7 @@ class phpbb_template_compile
 	/**
 	* Compiles template in $source_file and writes compiled template to
 	* cache directory
+	*
 	* @param string $handle Template handle to compile
 	* @param string $source_file Source template file
 	* @return bool Return true on success otherwise false
@@ -71,7 +77,9 @@ class phpbb_template_compile
 
 	/**
 	* Compiles a template located at $source_file.
+	*
 	* Returns PHP source suitable for eval().
+	*
 	* @param string $source_file Source template file
 	* @return string|bool Return compiled code on successful compilation otherwise false
 	*/

phpBB/includes/template/context.php

@@ -28,6 +28,7 @@ class phpbb_template_context
 	* --> $this->tpldata[block][iteration#][child][iteration#][child2][iteration#][variablename] == value
 	* if it's a root-level variable, it'll be like this:
 	* --> $this->tpldata[.][0][varname] == value
+	*
 	* @var array
 	*/
 	private $tpldata = array('.' => array(0 => array()));
@@ -53,6 +54,7 @@ class phpbb_template_context
 
 	/**
 	* Assign a single variable to a single key
+	*
 	* @param string $varname Variable name
 	* @param string $varval Value to assign to variable
 	*/
@@ -99,6 +101,7 @@ class phpbb_template_context
 
 	/**
 	* Assign key variable pairs from an array to a specified block
+	*
 	* @param string $blockname Name of block to assign $vararray to
 	* @param array $vararray A hash of variable name => value pairs
 	*/
@@ -308,6 +311,7 @@ class phpbb_template_context
 
 	/**
 	* Reset/empty complete block
+	*
 	* @param string $blockname Name of block to destroy
 	*/
 	public function destroy_block_vars($blockname)

phpBB/includes/template/filter.php

@@ -66,7 +66,9 @@ class phpbb_template_filter extends php_user_filter
 	private $in_php;
 
 	/**
-	* Whether <!-- PHP --> tags are allowed
+	* Whether inline PHP code, <!-- PHP --> and <!-- INCLUDEPHP --> tags
+	* are allowed. If this is false all PHP code will be silently
+	* removed from the template during compilation.
 	*
 	* @var bool
 	*/
@@ -134,6 +136,15 @@ class phpbb_template_filter extends php_user_filter
 		return true;
 	}
 
+	/**
+	* Compiles a chunk of template.
+	*
+	* The chunk must comprise of one or more complete lines from the source
+	* template.
+	*
+	* @param string $data Chunk of source template to compile
+	* @return string Compiled PHP/HTML code
+	*/
 	private function compile($data)
 	{
 		$block_start_in_php = $this->in_php;
@@ -192,6 +203,7 @@ class phpbb_template_filter extends php_user_filter
 	/**
 	* Prepends a preamble to compiled template.
 	* Currently preamble checks if IN_PHPBB is defined and calls exit() if it is not.
+	*
 	* @param string $data Compiled template chunk
 	* @return string Compiled template chunk with preamble prepended
 	*/
@@ -203,6 +215,9 @@ class phpbb_template_filter extends php_user_filter
 
 	/**
 	* Callback for replacing matched tokens with PHP code
+	*
+	* @param array $matches Regular expression matches
+	* @return string compiled template code
 	*/
 	private function replace($matches)
 	{
@@ -293,6 +308,9 @@ class phpbb_template_filter extends php_user_filter
 
 	/**
 	* Compile variables
+	*
+	* @param string $text_blocks Variable reference in source template
+	* @return string compiled template code
 	*/
 	private function compile_var_tags(&$text_blocks)
 	{
@@ -323,6 +341,8 @@ class phpbb_template_filter extends php_user_filter
 
 	/**
 	* Handles special language tags L_ and LA_
+	*
+	* @param string $text_blocks Variable reference in source template
 	*/
 	private function compile_language_tags(&$text_blocks)
 	{
@@ -342,6 +362,9 @@ class phpbb_template_filter extends php_user_filter
 
 	/**
 	* Compile blocks
+	*
+	* @param string $tag_args Block contents in source template
+	* @return string compiled template code
 	*/
 	private function compile_tag_block($tag_args)
 	{
@@ -454,6 +477,9 @@ class phpbb_template_filter extends php_user_filter
 	/**
 	* Compile a general expression - much of this is from Smarty with
 	* some adaptions for our block level methods
+	*
+	* @param string $tag_args Expression (tag arguments) in source template
+	* @return string compiled template code
 	*/
 	private function compile_expression($tag_args)
 	{
@@ -647,6 +673,10 @@ class phpbb_template_filter extends php_user_filter
 
 	/**
 	* Compile IF tags
+	*
+	* @param string $tag_args Expression given with IF in source template
+	* @param bool $elseif True if compiling an IF tag, false if compiling an ELSEIF tag
+	* @return string compiled template code
 	*/
 	private function compile_tag_if($tag_args, $elseif)
 	{
@@ -662,6 +692,10 @@ class phpbb_template_filter extends php_user_filter
 
 	/**
 	* Compile DEFINE tags
+	*
+	* @param string $tag_args Expression given with DEFINE in source template
+	* @param bool $op True if compiling a DEFINE tag, false if compiling an UNDEFINE tag
+	* @return string compiled template code
 	*/
 	private function compile_tag_define($tag_args, $op)
 	{
@@ -685,6 +719,9 @@ class phpbb_template_filter extends php_user_filter
 
 	/**
 	* Compile INCLUDE tag
+	*
+	* @param string $tag_args Expression given with INCLUDE in source template
+	* @return string compiled template code
 	*/
 	private function compile_tag_include($tag_args)
 	{
@@ -693,6 +730,9 @@ class phpbb_template_filter extends php_user_filter
 
 	/**
 	* Compile INCLUDE_PHP tag
+	*
+	* @param string $tag_args Expression given with INCLUDEPHP in source template
+	* @return string compiled template code
 	*/
 	private function compile_tag_include_php($tag_args)
 	{

phpBB/includes/template/locator.php

@@ -90,6 +90,7 @@ class phpbb_template_locator
 	/**
 	* Sets the template filenames for handles. $filename_array
 	* should be a hash of handle => filename pairs.
+	*
 	* @param array $filname_array Should be a hash of handle => filename pairs.
 	*/
 	public function set_filenames(array $filename_array)

phpBB/includes/template/renderer.php

@@ -27,6 +27,7 @@ interface phpbb_template_renderer
 {
 	/**
 	* Displays the template managed by this renderer.
+	*
 	* @param phpbb_template_context $context Template context to use
 	* @param array $lang Language entries to use
 	*/

phpBB/includes/template/renderer_eval.php

@@ -44,6 +44,7 @@ class phpbb_template_renderer_eval implements phpbb_template_renderer
 	/**
 	* Displays the template managed by this renderer by eval'ing php code
 	* of the template.
+	*
 	* @param phpbb_template_context $context Template context to use
 	* @param array $lang Language entries to use
 	*/

phpBB/includes/template/renderer_include.php

@@ -44,6 +44,7 @@ class phpbb_template_renderer_include implements phpbb_template_renderer
 	/**
 	* Displays the template managed by this renderer by including
 	* the php file containing the template.
+	*
 	* @param phpbb_template_context $context Template context to use
 	* @param array $lang Language entries to use
 	*/