From cc5f3c4005f696ff73c3da640dc2967051777c9f Mon Sep 17 00:00:00 2001 From: Tobias Schultze Date: Thu, 10 Oct 2013 00:52:04 +0200 Subject: [PATCH] fix phpdoc for environment, lexer and parser --- lib/Twig/Compiler.php | 2 + lib/Twig/Environment.php | 46 ++++++++++++++++++++++++++++++++++------- lib/Twig/Extension/Core.php | 10 ++++---- lib/Twig/Lexer.php | 7 +----- lib/Twig/LexerInterface.php | 2 + lib/Twig/Parser.php | 6 +---- lib/Twig/ParserInterface.php | 2 + 7 files changed, 51 insertions(+), 24 deletions(-) diff --git a/lib/Twig/Compiler.php b/lib/Twig/Compiler.php index b80210b..7a87cf8 100644 --- a/lib/Twig/Compiler.php +++ b/lib/Twig/Compiler.php @@ -253,6 +253,8 @@ class Twig_Compiler implements Twig_CompilerInterface * @param integer $step The number of indentation to remove * * @return Twig_Compiler The current compiler instance + * + * @throws LogicException When trying to outdent too much so the indentation would become negative */ public function outdent($step = 1) { diff --git a/lib/Twig/Environment.php b/lib/Twig/Environment.php index b2b80d0..1f32fa7 100644 --- a/lib/Twig/Environment.php +++ b/lib/Twig/Environment.php @@ -241,7 +241,7 @@ class Twig_Environment * * @param string $name The template name * - * @return string The cache file name + * @return string|false The cache file name or false when caching is disabled */ public function getCacheFilename($name) { @@ -290,6 +290,10 @@ class Twig_Environment * @param array $context An array of parameters to pass to the template * * @return string The rendered template + * + * @throws Twig_Error_Loader When the template cannot be found + * @throws Twig_Error_Syntax When an error occurred during compilation + * @throws Twig_Error_Runtime When an error occurred during rendering */ public function render($name, array $context = array()) { @@ -301,6 +305,10 @@ class Twig_Environment * * @param string $name The template name * @param array $context An array of parameters to pass to the template + * + * @throws Twig_Error_Loader When the template cannot be found + * @throws Twig_Error_Syntax When an error occurred during compilation + * @throws Twig_Error_Runtime When an error occurred during rendering */ public function display($name, array $context = array()) { @@ -314,6 +322,9 @@ class Twig_Environment * @param integer $index The index if it is an embedded template * * @return Twig_TemplateInterface A template instance representing the given template name + * + * @throws Twig_Error_Loader When the template cannot be found + * @throws Twig_Error_Syntax When an error occurred during compilation */ public function loadTemplate($name, $index = null) { @@ -366,6 +377,19 @@ class Twig_Environment return $this->getLoader()->isFresh($name, $time); } + /** + * Tries to load a template consecutively from an array. + * + * Similar to loadTemplate() but it also accepts Twig_TemplateInterface instances and an array + * of templates where each is tried to be loaded. + * + * @param string|Twig_Template|array $names A template or an array of templates to try consecutively + * + * @return Twig_Template + * + * @throws Twig_Error_Loader When none of the templates can be found + * @throws Twig_Error_Syntax When an error occurred during compilation + */ public function resolveTemplate($names) { if (!is_array($names)) { @@ -445,6 +469,8 @@ class Twig_Environment * @param string $name The template name * * @return Twig_TokenStream A Twig_TokenStream instance + * + * @throws Twig_Error_Syntax When the code is syntactically wrong */ public function tokenize($source, $name = null) { @@ -476,15 +502,17 @@ class Twig_Environment } /** - * Parses a token stream. + * Converts a token stream to a node tree. + * + * @param Twig_TokenStream $stream A token stream instance * - * @param Twig_TokenStream $tokens A Twig_TokenStream instance + * @return Twig_Node_Module A node tree * - * @return Twig_Node_Module A Node tree + * @throws Twig_Error_Syntax When the token stream is syntactically or semantically wrong */ - public function parse(Twig_TokenStream $tokens) + public function parse(Twig_TokenStream $stream) { - return $this->getParser()->parse($tokens); + return $this->getParser()->parse($stream); } /** @@ -512,7 +540,7 @@ class Twig_Environment } /** - * Compiles a Node. + * Compiles a node and returns the PHP code. * * @param Twig_NodeInterface $node A Twig_NodeInterface instance * @@ -530,6 +558,8 @@ class Twig_Environment * @param string $name The template name * * @return string The compiled PHP source code + * + * @throws Twig_Error_Syntax When there was an error during tokenizing, parsing or compiling */ public function compileSource($source, $name = null) { @@ -539,7 +569,7 @@ class Twig_Environment $e->setTemplateFile($name); throw $e; } catch (Exception $e) { - throw new Twig_Error_Runtime(sprintf('An exception has been thrown during the compilation of a template ("%s").', $e->getMessage()), -1, $name, $e); + throw new Twig_Error_Syntax(sprintf('An exception has been thrown during the compilation of a template ("%s").', $e->getMessage()), -1, $name, $e); } } diff --git a/lib/Twig/Extension/Core.php b/lib/Twig/Extension/Core.php index e03bb3c..e887143 100644 --- a/lib/Twig/Extension/Core.php +++ b/lib/Twig/Extension/Core.php @@ -1319,11 +1319,11 @@ function twig_test_iterable($value) /** * Renders a template. * - * @param string $template The template to render - * @param array $variables The variables to pass to the template - * @param Boolean $with_context Whether to pass the current context variables or not - * @param Boolean $ignore_missing Whether to ignore missing templates or not - * @param Boolean $sandboxed Whether to sandbox the template or not + * @param string|array $template The template to render or an array of templates to try consecutively + * @param array $variables The variables to pass to the template + * @param Boolean $with_context Whether to pass the current context variables or not + * @param Boolean $ignore_missing Whether to ignore missing templates or not + * @param Boolean $sandboxed Whether to sandbox the template or not * * @return string The rendered template */ diff --git a/lib/Twig/Lexer.php b/lib/Twig/Lexer.php index 000b038..e34fdd7 100644 --- a/lib/Twig/Lexer.php +++ b/lib/Twig/Lexer.php @@ -73,12 +73,7 @@ class Twig_Lexer implements Twig_LexerInterface } /** - * Tokenizes a source code. - * - * @param string $code The source code - * @param string $filename A unique identifier for the source code - * - * @return Twig_TokenStream A token stream instance + * {@inheritdoc} */ public function tokenize($code, $filename = null) { diff --git a/lib/Twig/LexerInterface.php b/lib/Twig/LexerInterface.php index 4b83f81..dd51cae 100644 --- a/lib/Twig/LexerInterface.php +++ b/lib/Twig/LexerInterface.php @@ -24,6 +24,8 @@ interface Twig_LexerInterface * @param string $filename A unique identifier for the source code * * @return Twig_TokenStream A token stream instance + * + * @throws Twig_Error_Syntax When the code is syntactically wrong */ public function tokenize($code, $filename = null); } diff --git a/lib/Twig/Parser.php b/lib/Twig/Parser.php index c0ac105..73f197f 100644 --- a/lib/Twig/Parser.php +++ b/lib/Twig/Parser.php @@ -58,11 +58,7 @@ class Twig_Parser implements Twig_ParserInterface } /** - * Converts a token stream to a node tree. - * - * @param Twig_TokenStream $stream A token stream instance - * - * @return Twig_Node_Module A node tree + * {@inheritdoc} */ public function parse(Twig_TokenStream $stream, $test = null, $dropNeedle = false) { diff --git a/lib/Twig/ParserInterface.php b/lib/Twig/ParserInterface.php index f0d7900..bfe60a3 100644 --- a/lib/Twig/ParserInterface.php +++ b/lib/Twig/ParserInterface.php @@ -23,6 +23,8 @@ interface Twig_ParserInterface * @param Twig_TokenStream $stream A token stream instance * * @return Twig_Node_Module A node tree + * + * @throws Twig_Error_Syntax When the token stream is syntactically or semantically wrong */ public function parse(Twig_TokenStream $stream); } -- 1.7.2.5