diff --git a/core/lib/Drupal/Core/Template/TwigEnvironment.php b/core/lib/Drupal/Core/Template/TwigEnvironment.php index 4851919..12baead 100644 --- a/core/lib/Drupal/Core/Template/TwigEnvironment.php +++ b/core/lib/Drupal/Core/Template/TwigEnvironment.php @@ -8,7 +8,12 @@ namespace Drupal\Core\Template; /** - * @todo Document me! Pleeeeease :) + * A class that defines a Twig environment for Drupal. + * + * Instances of this class are used to store the configuration and extensions, + * and are used to load templates from the file system or other locations. + * + * @see core\vendor\twig\twig\lib\Twig\Enviornment.php */ class TwigEnvironment extends \Twig_Environment { protected $cacheO = NULL; diff --git a/core/lib/Drupal/Core/Template/TwigFactory.php b/core/lib/Drupal/Core/Template/TwigFactory.php index 727e4b2..4bb297e 100644 --- a/core/lib/Drupal/Core/Template/TwigFactory.php +++ b/core/lib/Drupal/Core/Template/TwigFactory.php @@ -47,14 +47,16 @@ public static function get() { $twig = new TwigEnvironment($loader, array( // This is saved / loaded via drupal_php_storage(). // All files can be refreshed via drush cc all. - // @todo ensure garbage collection of expired files + // @todo ensure garbage collection of expired files. 'cache' => TRUE, 'base_template_class' => 'Drupal\Core\Template\TwigTemplate', - // @todo Remove in followup issue. + // @todo Remove in followup issue + // @see http://drupal.org/node/1712444. 'autoescape' => FALSE, - // @todo Remove in followup issue to handle exceptions gracefully. + // @todo Remove in followup issue + // @see http://drupal.org/node/1806538. 'strict_variables' => FALSE, - // @todo Maybe make debug mode dependent on "production mode" setting + // @todo Maybe make debug mode dependent on "production mode" setting. 'debug' => TRUE, )); diff --git a/core/lib/Drupal/Core/Template/TwigFunctionTokenParser.php b/core/lib/Drupal/Core/Template/TwigFunctionTokenParser.php index 5291d95..2d123cc 100644 --- a/core/lib/Drupal/Core/Template/TwigFunctionTokenParser.php +++ b/core/lib/Drupal/Core/Template/TwigFunctionTokenParser.php @@ -8,24 +8,38 @@ namespace Drupal\Core\Template; /** - * @todo Document me! + * A class that defines the Twig token parser for Drupal. + * + * The token parser converts a token stream created from template source + * code into an Abstract Syntax Tree (AST). The AST will later be compiled + * into PHP code usable for runtime execution of the template. + * + * @see core\vendor\twig\twig\lib\Twig\TokenParser.php */ class TwigFunctionTokenParser extends \Twig_TokenParser { /** - * @todo Document me! + * The name of tag. Can be 'hide' or 'show'. + * + * @var string */ protected $tag; /** - * @todo Document me! + * Constructor for TwigFunctionTokenParser. + * + * Locally scope variables. */ public function __construct($tag = 'hide') { $this->tag = $tag; } /** - * @todo Document me! + * Parses a token and returns a node. + * + * @param Twig_Token $token A Twig_Token instance. + * + * @return Twig_Node_Print A Twig_Node_Print instance. */ public function parse(\Twig_Token $token) { $lineno = $token->getLine(); @@ -36,7 +50,9 @@ public function parse(\Twig_Token $token) { } /** - * @todo Document me! + * Gets the tag name associated with this token parser. + * + * @return string The tag name */ public function getTag() { return $this->tag; diff --git a/core/lib/Drupal/Core/Template/TwigNodeExpressionNameReference.php b/core/lib/Drupal/Core/Template/TwigNodeExpressionNameReference.php index a841df2..c66d73f 100644 --- a/core/lib/Drupal/Core/Template/TwigNodeExpressionNameReference.php +++ b/core/lib/Drupal/Core/Template/TwigNodeExpressionNameReference.php @@ -8,11 +8,15 @@ namespace Drupal\Core\Template; /** - * @todo Document me! + * A class that defines a reference to the name for all nodes that represent + * expressions. + * + * @see core\vendor\twig\twig\lib\Twig\Node\Expression\Name.php */ class TwigNodeExpressionNameReference extends \Twig_Node_Expression_Name { + /** - * @todo document me + * Overrides Twig_Node_Expression_Name::compile(). */ public function compile(\Twig_Compiler $compiler) { $name = $this->getAttribute('name'); @@ -21,4 +25,5 @@ public function compile(\Twig_Compiler $compiler) { ->string($name) ->raw(')'); } + } diff --git a/core/lib/Drupal/Core/Template/TwigNodeVisitor.php b/core/lib/Drupal/Core/Template/TwigNodeVisitor.php index f08f071..0cf5465 100644 --- a/core/lib/Drupal/Core/Template/TwigNodeVisitor.php +++ b/core/lib/Drupal/Core/Template/TwigNodeVisitor.php @@ -11,7 +11,7 @@ * Provides a Twig_NodeVisitor to change the generated parse-tree. * * This is used to ensure that everything that is printed is wrapped via - * twig_render() function so that we can write for example just {{ content }} + * twig_render() function so that we can write for example just {{ content }} * in templates instead of having to write {{ render(content) }}. * * @see twig_render @@ -19,7 +19,11 @@ class TwigNodeVisitor implements \Twig_NodeVisitorInterface { /** - * @todo document me + * TRUE when this node is a function getting arguments by reference. + * + * For example: 'hide' or 'render' are such functions. + * + * @var bool */ protected $isReference = FALSE; @@ -27,8 +31,6 @@ class TwigNodeVisitor implements \Twig_NodeVisitorInterface { * Implements Twig_NodeVisitorInterface::enterNode(). */ function enterNode(\Twig_NodeInterface $node, \Twig_Environment $env) { - - // @todo Document this if ($node instanceof \Twig_Node_Expression_Function) { $name = $node->getAttribute('name'); $func = $env->getFunction($name); @@ -70,7 +72,7 @@ function leaveNode(\Twig_NodeInterface $node, \Twig_Environment $env) { } if ($this->isReference) { - if ( $node instanceof \Twig_Node_Expression_Name) { + if ($node instanceof \Twig_Node_Expression_Name) { $name = $node->getAttribute('name'); return new TwigNodeExpressionNameReference($name, $node->getLine()); } diff --git a/core/lib/Drupal/Core/Template/TwigReferenceFunction.php b/core/lib/Drupal/Core/Template/TwigReferenceFunction.php index 5fed071..6ca4cbd 100644 --- a/core/lib/Drupal/Core/Template/TwigReferenceFunction.php +++ b/core/lib/Drupal/Core/Template/TwigReferenceFunction.php @@ -8,7 +8,7 @@ namespace Drupal\Core\Template; /** - * @todo Document me! + * This class is used to create functions requiring references like 'hide'. */ class TwigReferenceFunction extends \Twig_Function_Function { } diff --git a/core/lib/Drupal/Core/Template/TwigTemplate.php b/core/lib/Drupal/Core/Template/TwigTemplate.php index b23892c..fdc5d31 100644 --- a/core/lib/Drupal/Core/Template/TwigTemplate.php +++ b/core/lib/Drupal/Core/Template/TwigTemplate.php @@ -8,21 +8,38 @@ namespace Drupal\Core\Template; /** - * @todo Document me! + * This is the base class for compiled Twig templates. */ abstract class TwigTemplate extends \Twig_Template { - // @todo: Document me - private $twig_reference = NULL; + /** + * A class used to pass variables by reference while they are used in Twig. + */ + protected $twig_reference = NULL; - // This assumes that no template uses a top level var once as render array, once as normal var + /** + * List of the name of variables to be passed around as references. + * + * @var array + */ protected $is_reference = array(); + + /** + * List of the name of variables to be passed around by value. + * + * @var array + */ protected $is_no_reference = array(); /** - * @todo Document me! - */ - final protected function getContextReference(&$context, $item, $ignoreStrictCheck = TRUE) + * @param array $context + * The variables available to the template. + * @param $item + * The name of the variable. + * @return mixed + * The requested variable. + */ + final protected function getContextReference(&$context, $item) { // Optimized version if (!isset($context[$item])) { @@ -31,7 +48,7 @@ // @todo Decide based on prod vs. dev setting $msg = new \Twig_Error(t('@item could not be found in _context.', array('@item' => $item))); drupal_set_message($msg->getMessage(), 'warning'); - return null; + return NULL; } // The first test also finds empty / null render arrays diff --git a/core/modules/node/templates/node.twig b/core/modules/node/templates/node.twig index 60e9cdb..4c79e66 100644 --- a/core/modules/node/templates/node.twig +++ b/core/modules/node/templates/node.twig @@ -4,22 +4,22 @@ * Default theme implementation to display a node. * * Available variables: - * - label: the (sanitized) title of the node. - * - content: An array of node items. Use {{ content }} to print them all, + * - label: the title of the node. + * - content: node items. Use {{ content }} to print them all, * or print a subset such as {{ content.field_example }}. Use * {% hide(content.field_example) %} to temporarily suppress the printing * of a given element. * - user_picture: The node author's picture from user-picture.twig. * - date: Formatted creation date. Preprocess functions can reformat it by - * calling format_date() with the desired parameters on the $created variable. + * calling format_date() with the desired parameters on + * $variables['created']. * - name: Themed username of node author output from theme_username(). * - node_url: Direct URL of the current node. * - display_submitted: Whether submission information should be displayed. - * - submitted: Submission information created from $name and $date during + * - submitted: Submission information created from name and date during * template_preprocess_node(). - * - attributes: An instance of Attributes class that can be manipulated as an - * array and printed as a string. - * It includes the 'class' information, which includes: + * - attributes: HTML attributes for the surrounding element. + * Attributes include the 'class' information, which contains: * - node: The current template type; for example, "theming hook". * - node-[type]: The current node type. For example, if the node is a * "Article" it would result in "node-article". Note that the machine @@ -38,28 +38,30 @@ * displayed after the main title tag that appears in the template. * * Other variables: - * - node: Full node entity. Contains data that may not be safe. + * - node: Fully loaded node entity. * - type: Node type; for example, page, article, etc. * - comment_count: Number of comments attached to the node. * - uid: User ID of the node author. - * - created: Time the node was published formatted in Unix timestamp. + * - created: Time the node was published formatted as a Unix timestamp. * - zebra: Outputs either "even" or "odd". Useful for zebra striping in * teaser listings. * - id: Position of the node. Increments each time it's output. * * Node status variables: * - view_mode: View mode; for example, "teaser" or "full". - * - teaser: Flag for the teaser state (shortcut for $view_mode == 'teaser'). - * - page: Flag for the full page state. + * - teaser: Flag for the teaser state. Will be true if view_mode is 'teaser'. + * - page: Flag for the full page state. Will be true if view_mode is 'full'. * - promote: Flag for front page promotion state. - * - sticky: Flags for sticky post setting. + * - sticky: Flag for sticky post setting. * - status: Flag for published status. * - comment: State of comment settings for the node. - * - readmore: Flags true if the teaser content of the node cannot hold the - * main body content. - * - is_front: Flags true when presented in the front page. - * - logged_in: Flags true when the current user is a logged-in member. - * - is_admin: Flags true when the current user is an administrator. + * - readmore: Flag for more state. Will be true if the teaser content of the + * node cannot hold the main body content. + * - is_front: Flag for front. Will be true when presented on the front page. + * - logged_in: Flag for authenticated user status. Will be true when the + * current user is a logged-in member. + * - is_admin: Flag for admin user status. Will be true when the current user + * is an administrator. * * Field variables: for each field instance attached to the node a corresponding * variable is defined; for example, $node->body becomes body. When needing to diff --git a/core/modules/system/templates/datetime.twig b/core/modules/system/templates/datetime.twig index b6c6f21..fa21e33 100644 --- a/core/modules/system/templates/datetime.twig +++ b/core/modules/system/templates/datetime.twig @@ -2,31 +2,27 @@ /** * Returns HTML for a date / time. * - * @param $variables - * An associative array containing: - * - timestamp: (optional) A UNIX timestamp for the datetime attribute. If the - * datetime cannot be represented as a UNIX timestamp, use a valid datetime - * attribute value in $variables['attributes']['datetime']. - * - text: (optional) The content to display within the