Index: MediaWiki/branches/1.11/includes/api/ApiFormatBase.php
===================================================================
--- MediaWiki/branches/1.11/includes/api/ApiFormatBase.php	(revision 1280)
+++ MediaWiki/branches/1.11/includes/api/ApiFormatBase.php	(revision 1281)
@@ -6,5 +6,5 @@
  * API for MediaWiki 1.8+
  *
- * Copyright (C) 2006 Yuri Astrakhan <FirstnameLastname@gmail.com>
+ * Copyright (C) 2006 Yuri Astrakhan <Firstname><Lastname>@gmail.com
  *
  * This program is free software; you can redistribute it and/or modify
@@ -30,4 +30,6 @@
 
 /**
+ * This is the abstract base class for API formatters.
+ * 
  * @addtogroup API
  */
@@ -37,5 +39,6 @@
 
 	/**
-	* Constructor
+	* Create a new instance of the formatter.
+	* If the format name ends with 'fm', wrap its output in the proper HTML.
 	*/
 	public function __construct($main, $format) {
@@ -57,4 +60,9 @@
 	public abstract function getMimeType();
 
+	/**
+	 * If formatter outputs data results as is, the results must first be sanitized.
+	 * An XML formatter on the other hand uses special tags, such as "_element" for special handling,
+	 * and thus needs to override this function to return true.  
+	 */
 	public function getNeedsRawData() {
 		return false;
@@ -78,4 +86,5 @@
 		$isHtml = $this->getIsHtml();
 		$mime = $isHtml ? 'text/html' : $this->getMimeType();
+		$script = wfScript( 'api' );
 
 		// Some printers (ex. Feed) do their own header settings,
@@ -97,12 +106,12 @@
 
 
-			if (!$isError) {
+			if( !$isError ) {
 ?>
 <br/>
 <small>
-You are looking at the HTML representation of the <?=$this->mFormat?> format.<br/>
+You are looking at the HTML representation of the <?php echo( $this->mFormat ); ?> format.<br/>
 HTML is good for debugging, but probably is not suitable for your application.<br/>
-Please see "format" parameter documentation at the <a href='api.php'>API help</a>
-for more information.
+See <a href='http://www.mediawiki.org/wiki/API'>complete documentation</a>, or 
+<a href='<?php echo( $script ); ?>'>API help</a> for more information.
 </small>
 <?php
@@ -134,4 +143,8 @@
 	}
 
+	/**
+	 * The main format printing function. Call it to output the result string to the user.
+	 * This function will automatically output HTML when format name ends in 'fm'.
+	 */
 	public function printText($text) {
 		if ($this->getIsHtml())
@@ -146,11 +159,14 @@
 	*/
 	protected function formatHTML($text) {
-		// encode all tags as safe blue strings
-		$text = ereg_replace('\<([^>]+)\>', '<span style="color:blue;">&lt;\1&gt;</span>', $text);
+		// Escape everything first for full coverage
+		$text = htmlspecialchars($text);
+		
+		// encode all comments or tags as safe blue strings
+		$text = preg_replace('/\&lt;(!--.*?--|.*?)\&gt;/', '<span style="color:blue;">&lt;\1&gt;</span>', $text);
 		// identify URLs
 		$protos = "http|https|ftp|gopher";
-		$text = ereg_replace("($protos)://[^ '\"()<\n]+", '<a href="\\0">\\0</a>', $text);
+		$text = ereg_replace("($protos)://[^ \\'\"()<\n]+", '<a href="\\0">\\0</a>', $text);
 		// identify requests to api.php
-		$text = ereg_replace("api\\.php\\?[^ ()<\n\t]+", '<a href="\\0">\\0</a>', $text);
+		$text = ereg_replace("api\\.php\\?[^ \\()<\n\t]+", '<a href="\\0">\\0</a>', $text);
 		// make strings inside * bold
 		$text = ereg_replace("\\*[^<>\n]+\\*", '<b>\\0</b>', $text);
@@ -173,5 +189,5 @@
 
 	public static function getBaseVersion() {
-		return __CLASS__ . ': $Id: ApiFormatBase.php 21402 2007-04-20 08:55:14Z nickj $';
+		return __CLASS__ . ': $Id: ApiFormatBase.php 25746 2007-09-10 21:36:51Z brion $';
 	}
 }
@@ -188,5 +204,5 @@
 
 	/**
-	 * Call this method to initialize output data
+	 * Call this method to initialize output data. See self::execute()
 	 */
 	public static function setResult($result, $feed, $feedItems) {
@@ -212,4 +228,9 @@
 	}
 
+	/**
+	 * This class expects the result data to be in a custom format set by self::setResult()
+	 * $result['_feed']		 - an instance of one of the $wgFeedClasses classes
+	 * $result['_feeditems'] - an array of FeedItem instances
+	 */
 	public function execute() {
 		$data = $this->getResultData();
@@ -230,6 +251,5 @@
 	
 	public function getVersion() {
-		return __CLASS__ . ': $Id: ApiFormatBase.php 21402 2007-04-20 08:55:14Z nickj $';
+		return __CLASS__ . ': $Id: ApiFormatBase.php 25746 2007-09-10 21:36:51Z brion $';
 	}
 }
-?>