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

Added notes about the 'extended' return values from some of the hooks, which seems to be undocumented but is vaguely similar to what is documented for parser function callbacks. It doesn't look like a very safe interface, and could stomp on internal variables if one isn't careful. Needs to be better defined and doc'd.

setTransparentTagHook() seems to have been largely undocumented and is only used by the 'geoserver' extension currently. Is this considered obsolete? Should it be simply replaced by use of the frame & recursiveTagParse goodies, or is it still needed for something?

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 );

diff --git a/includes/parser/Parser.php b/includes/parser/Parser.php
index 0158416..ad4ba77 100644 (file)
--- a/includes/parser/Parser.php
+++ b/includes/parser/Parser.php
@@ -4486,11 +4486,22 @@ class Parser {
        /**
         * Create an HTML-style tag, e.g. <yourtag>special text</yourtag>
         * The callback should have the following form:
-        *    function myParserHook( $text, $params, $parser ) { ... }
+        *    function myParserHook( $text, $params, $parser, $frame ) { ... }
         *
         * Transform and return $text. Use $parser for any required context, e.g. use
         * $parser->getTitle() and $parser->getOptions() not $wgTitle or $wgOut->mParserOptions
         *
+        * Hooks may return extended information by returning an array, of which the
+        * first numbered element (index 0) must be the return string, and all other
+        * entries are extracted into local variables within an internal function
+        * in the Parser class.
+        *
+        * This interface (introduced r61913) appears to be undocumented, but
+        * 'markerName' is used by some core tag hooks to override which strip
+        * array their results are placed in. **Use great caution if attempting
+        * this interface, as it is not documented and injudicious use could smash
+        * private variables.**
+        *
         * @param $tag Mixed: the tag to use, e.g. 'hook' for <hook>
         * @param $callback Mixed: the callback function (and object) to use for the tag
         * @return The old value of the mTagHooks array associated with the hook
@@ -4507,6 +4518,22 @@ class Parser {
                return $oldVal;
        }
 
+       /**
+        * As setHook(), but letting the contents be parsed.
+        *
+        * Transparent tag hooks are like regular XML-style tag hooks, except they
+        * operate late in the transformation sequence, on HTML instead of wikitext.
+        *
+        * This is probably obsoleted by things dealing with parser frames?
+        * The only extension currently using it is geoserver.
+        *
+        * @since 1.10
+        * @todo better document or deprecate this
+        *
+        * @param $tag Mixed: the tag to use, e.g. 'hook' for <hook>
+        * @param $callback Mixed: the callback function (and object) to use for the tag
+        * @return The old value of the mTagHooks array associated with the hook
+        */
        function setTransparentTagHook( $tag, $callback ) {
                $tag = strtolower( $tag );
                if ( preg_match( '/[<>\r\n]/', $tag, $m ) ) throw new MWException( "Invalid character {$m[0]} in setTransparentHook('$tag', ...) call" );
@@ -4655,6 +4682,10 @@ class Parser {
         * given as text will return the HTML of a gallery with two images,
         * labeled 'The number "1"' and
         * 'A tree'.
+        *
+        * @param string $text
+        * @param array $param
+        * @return string HTML
         */
        function renderImageGallery( $text, $params ) {
                $ig = new ImageGallery();