Doc comment updates for CoreTagHooks callback functions + Parser::setHook() & Parser...

[lhc/web/wiklou.git] / includes / parser / CoreTagHooks.php

diff --git a/includes/parser/CoreTagHooks.php b/includes/parser/CoreTagHooks.php
index 1eb24f4..381ed5a 100644 (file)
--- a/includes/parser/CoreTagHooks.php
+++ b/includes/parser/CoreTagHooks.php
@@ -24,6 +24,16 @@ class CoreTagHooks {
                }
        }
 
+       /**
+        * Core parser tag hook function for 'pre'.
+        * Text is treated roughly as 'nowiki' wrapped in an HTML 'pre' tag;
+        * valid HTML attributes are passed on.
+        *
+        * @param string $text
+        * @param array $attribs
+        * @param Parser $parser
+        * @return string HTML
+        */
        static function pre( $text, $attribs, $parser ) {
                // Backwards-compatibility hack
                $content = StringUtils::delimiterReplace( '<nowiki>', '</nowiki>', '$1', $text, 'i' );
@@ -34,6 +44,20 @@ class CoreTagHooks {
                        '</pre>';
        }
 
+       /**
+        * Core parser tag hook function for 'html', used only when
+        * $wgRawHtml is enabled.
+        *
+        * This is potentially unsafe and should be used only in very careful
+        * circumstances, as the contents are emitted as raw HTML.
+        *
+        * Uses undocumented extended tag hook return values, introduced in r61913.
+        *
+        * @param string $content
+        * @param array $attribs
+        * @param Parser $parser
+        * @return array
+        */
        static function html( $content, $attributes, $parser ) {
                global $wgRawHtml;
                if( $wgRawHtml ) {
@@ -43,16 +67,37 @@ class CoreTagHooks {
                }
        }
 
+       /**
+        * Core parser tag hook function for 'nowiki'. Text within this section
+        * gets interpreted as a string of text with HTML-compatible character
+        * references, and wiki markup within it will not be expanded.
+        *
+        * Uses undocumented extended tag hook return values, introduced in r61913.
+        *
+        * @param string $content
+        * @param array $attribs
+        * @param Parser $parser
+        * @return array
+        */
        static function nowiki( $content, $attributes, $parser ) {
                $content = strtr( $content, array( '-{' => '-&#123;', '}-' => '&#125;-' ) );
                return array( Xml::escapeTagsOnly( $content ), 'markerType' => 'nowiki' );
        }
 
        /**
-        * @param  $content
-        * @param  $attributes
-        * @param $parser Parser
-        * @return
+        * Core parser tag hook function for 'gallery'.
+        *
+        * Renders a thumbnail list of the given images, with optional captions.
+        * Full syntax documented on the wiki:
+        *
+        *   http://www.mediawiki.org/wiki/Help:Images#Gallery_syntax
+        *
+        * @todo break Parser::renderImageGallery out here too.
+        *
+        * @param string $content
+        * @param array $attributes
+        * @param Parser $parser
+        * @return string HTML
         */
        static function gallery( $content, $attributes, $parser ) {
                return $parser->renderImageGallery( $content, $attributes );