private $mIsHtml, $mFormat, $mUnescapeAmps, $mHelp, $mCleared;
/**
- * Create a new instance of the formatter.
- * If the format name ends with 'fm', wrap its output in the proper HTML.
- */
+ * Constructor
+ * If $format ends with 'fm', pretty-print the output in HTML.
+ * @param $main ApiMain
+ * @param $format string Format name
+ */
public function __construct($main, $format) {
parent :: __construct($main, $format);
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.
+ * Whether this formatter needs raw data such as _element tags
+ * @return bool
*/
public function getNeedsRawData() {
return false;
/**
* Get the internal format name
+ * @return string
*/
public function getFormat() {
return $this->mFormat;
}
/**
- * Specify whether or not ampersands should be escaped to '&' when rendering. This
- * should only be set to true for the help message when rendered in the default (xmlfm)
- * format. This is a temporary special-case fix that should be removed once the help
- * has been reworked to use a fully html interface.
+ * Specify whether or not sequences like " should be unescaped
+ * to " . This should only be set to true for the help message
+ * when rendered in the default (xmlfm) format. This is a temporary
+ * special-case fix that should be removed once the help has been
+ * reworked to use a fully HTML interface.
*
- * @param boolean Whether or not ampersands should be escaped.
+ * @param $b bool Whether or not ampersands should be escaped.
*/
public function setUnescapeAmps ( $b ) {
$this->mUnescapeAmps = $b;
}
/**
- * Returns true when an HTML filtering printer should be used.
+ * Returns true when the HTML pretty-printer should be used.
* The default implementation assumes that formats ending with 'fm'
* should be formatted in HTML.
+ * @return bool
*/
public function getIsHtml() {
return $this->mIsHtml;
}
/**
- * Initialize the printer function and prepares the output headers, etc.
+ * Initialize the printer function and prepare the output headers, etc.
* This method must be the first outputing method during execution.
* A help screen's header is printed for the HTML-based output
+ * @param $isError bool Whether an error message is printed
*/
function initPrinter($isError) {
$isHtml = $this->getIsHtml();
}
/**
- * 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'.
+ * 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'.
+ * @param $text string
*/
public function printText($text) {
if ($this->getIsHtml())
}
/**
- * Says pretty-printer that it should use *bold* and $italics$ formatting
- */
+ * Sets whether the pretty-printer should format *bold* and $italics$
+ * @param $help bool
+ */
public function setHelp( $help = true ) {
$this->mHelp = true;
}
/**
- * Prety-print various elements in HTML format, such as xml tags and URLs.
- * This method also replaces any '<' with <
+ * Prety-print various elements in HTML format, such as xml tags and
+ * URLs. This method also escapes characters like <
+ * @param $text string
+ * @return string
*/
protected function formatHTML($text) {
global $wgUrlProtocols;
return $text;
}
- /**
- * Returns usage examples for this format.
- */
protected function getExamples() {
return 'api.php?action=query&meta=siteinfo&siprop=namespaces&format=' . $this->getModuleName();
}
}
/**
- * Call this method to initialize output data. See self::execute()
+ * Call this method to initialize output data. See execute()
+ * @param $result ApiResult
+ * @param $feed object an instance of one of the $wgFeedClasses classes
+ * @param $feedItems array of FeedItem objects
*/
public static function setResult($result, $feed, $feedItems) {
// Store output in the Result data.
}
/**
- * This is the main query class. It behaves similar to ApiMain: based on the parameters given,
- * it will create a list of titles to work on (an instance of the ApiPageSet object)
- * instantiate and execute various property/list/meta modules,
- * and assemble all resulting data into a single ApiResult object.
+ * This is the main query class. It behaves similar to ApiMain: based on the
+ * parameters given, it will create a list of titles to work on (an ApiPageSet
+ * object), instantiate and execute various property/list/meta modules, and
+ * assemble all resulting data into a single ApiResult object.
*
- * In the generator mode, a generator will be first executed to populate a second ApiPageSet object,
- * and that object will be used for all subsequent modules.
+ * In generator mode, a generator will be executed first to populate a second
+ * ApiPageSet object, and that object will be used for all subsequent modules.
*
* @ingroup API
*/
/**
* Helper function to append any add-in modules to the list
+ * @param $modules array Module array
+ * @param $newModules array Module array to add to $modules
*/
private static function appendUserModules(&$modules, $newModules) {
if (is_array( $newModules )) {
/**
* Gets a default slave database connection object
+ * @return Database
*/
public function getDB() {
if (!isset ($this->mSlaveDB)) {
* Get the query database connection with the given name.
* If no such connection has been requested before, it will be created.
* Subsequent calls with the same $name will return the same connection
- * as the first, regardless of $db or $groups new values.
+ * as the first, regardless of the values of $db and $groups
+ * @param $name string Name to assign to the database connection
+ * @param $db int One of the DB_* constants
+ * @param $groups array Query groups
+ * @return Database
*/
public function getNamedDB($name, $db, $groups) {
if (!array_key_exists($name, $this->mNamedDB)) {
/**
* Gets the set of pages the user has requested (or generated)
+ * @return ApiPageSet
*/
public function getPageSet() {
return $this->mPageSet;
/**
* Get the array mapping module names to class names
+ * @return array(modulename => classname)
*/
function getModules() {
return array_merge($this->mQueryPropModules, $this->mQueryListModules, $this->mQueryMetaModules);
/**
* Query execution happens in the following steps:
* #1 Create a PageSet object with any pages requested by the user
- * #2 If using generator, execute it to get a new PageSet object
+ * #2 If using a generator, execute it to get a new ApiPageSet object
* #3 Instantiate all requested modules.
* This way the PageSet object will know what shared data is required,
* and minimize DB calls.
* Query modules may optimize data requests through the $this->getPageSet() object
* by adding extra fields from the page table.
* This function will gather all the extra request fields from the modules.
+ * @param $modules array of module objects
+ * @param $pageSet ApiPageSet
*/
private function addCustomFldsToPageSet($modules, $pageSet) {
// Query all requested modules.
/**
* Create instances of all modules requested by the client
+ * @param $modules array to append instatiated modules to
+ * @param $param string Parameter name to read modules from
+ * @param $moduleList array(modulename => classname)
*/
private function InstantiateModules(&$modules, $param, $moduleList) {
$list = @$this->params[$param];
}
/**
- * Appends an element for each page in the current pageSet with the most general
- * information (id, title), plus any title normalizations and missing or invalid title/pageids/revids.
+ * Appends an element for each page in the current pageSet with the
+ * most general information (id, title), plus any title normalizations
+ * and missing or invalid title/pageids/revids.
*/
private function outputGeneralPageInfo() {
}
/**
- * For generator mode, execute generator, and use its output as new pageSet
+ * For generator mode, execute generator, and use its output as new
+ * ApiPageSet
+ * @param $generatorName string Module name
+ * @param $modules array of module objects
*/
protected function executeGeneratorModule($generatorName, $modules) {
$this->mPageSet = $resultPageSet;
}
- /**
- * Returns the list of allowed parameters for this module.
- * Qurey module also lists all ApiPageSet parameters as its own.
- */
public function getAllowedParams() {
return array (
'prop' => array (
/**
* Override the parent to generate help messages for all available query modules.
+ * @return string
*/
public function makeHelpMsg() {
/**
* For all modules in $moduleList, generate help messages and join them together
+ * @param $moduleList array(modulename => classname)
+ * @param $paramName string Parameter name
+ * @return string
*/
private function makeHelpMsgHelper($moduleList, $paramName) {
- $moduleDscriptions = array ();
+ $moduleDescriptions = array ();
foreach ($moduleList as $moduleName => $moduleClass) {
$module = new $moduleClass ($this, $moduleName, null);
$this->mAllowedGenerators[] = $moduleName;
$msg .= "Generator:\n This module may be used as a generator\n";
}
- $moduleDscriptions[] = $msg;
+ $moduleDescriptions[] = $msg;
}
- return implode("\n", $moduleDscriptions);
+ return implode("\n", $moduleDescriptions);
}
/**
* Override to add extra parameters from PageSet
+ * @return string
*/
public function makeHelpMsgParameters() {
$psModule = new ApiPageSet($this);
/**
* This is a base class for all Query modules.
- * It provides some common functionality such as constructing various SQL queries.
+ * It provides some common functionality such as constructing various SQL
+ * queries.
*
* @ingroup API
*/
/**
* Add a set of tables to the internal array
- * @param mixed $tables Table name or array of table names
- * @param mixed $alias Table alias, or null for no alias. Cannot be used with multiple tables
+ * @param $tables mixed Table name or array of table names
+ * @param $alias mixed Table alias, or null for no alias. Cannot be
+ * used with multiple tables
*/
protected function addTables($tables, $alias = null) {
if (is_array($tables)) {
/**
* Get the SQL for a table name with alias
- * @param string $table Table name
- * @param string $alias Alias
+ * @param $table string Table name
+ * @param $alias string Alias
* @return string SQL
*/
protected function getAliasedName($table, $alias) {
/**
* Add a set of JOIN conditions to the internal array
*
- * JOIN conditions are formatted as array( tablename => array(jointype, conditions)
- * e.g. array('page' => array('LEFT JOIN', 'page_id=rev_page'))
- * @param array $join_conds JOIN conditions
+ * JOIN conditions are formatted as array( tablename => array(jointype,
+ * conditions) e.g. array('page' => array('LEFT JOIN',
+ * 'page_id=rev_page')) . conditions may be a string or an
+ * addWhere()-style array
+ * @param $join_conds array JOIN conditions
*/
protected function addJoinConds($join_conds) {
if(!is_array($join_conds))
/**
* Add a set of fields to select to the internal array
- * @param mixed $value Field name or array of field names
+ * @param $value mixed Field name or array of field names
*/
protected function addFields($value) {
if (is_array($value))
/**
* Same as addFields(), but add the fields only if a condition is met
- * @param mixed $value See addFields()
- * @param bool $condition If false, do nothing
+ * @param $value mixed See addFields()
+ * @param $condition bool If false, do nothing
* @return bool $condition
*/
protected function addFieldsIf($value, $condition) {
*
* For example, array('foo=bar', 'baz' => 3, 'bla' => 'foo') translates
* to "foo=bar AND baz='3' AND bla='foo'"
- * @param mixed $value String or array
+ * @param $value mixed String or array
*/
protected function addWhere($value) {
if (is_array($value)) {
/**
* Same as addWhere(), but add the WHERE clauses only if a condition is met
- * @param mixed $value See addWhere()
- * @param bool $condition If false, do nothing
+ * @param $value mixed See addWhere()
+ * @param $condition boolIf false, do nothing
* @return bool $condition
*/
protected function addWhereIf($value, $condition) {
/**
* Equivalent to addWhere(array($field => $value))
- * @param string $field Field name
- * @param string $value Value; ignored if null or empty array;
+ * @param $field string Field name
+ * @param $value string Value; ignored if null or empty array;
*/
protected function addWhereFld($field, $value) {
// Use count() to its full documented capabilities to simultaneously
/**
* Add a WHERE clause corresponding to a range, and an ORDER BY
* clause to sort in the right direction
- * @param string $field Field name
- * @param string $dir If 'newer', sort in ascending order, otherwise sort in descending order
- * @param string $start Value to start the list at. If $dir == 'newer' this is the lower boundary, otherwise it's the upper boundary
- * @param string $end Value to end the list at. If $dir == 'newer' this is the upper boundary, otherwise it's the lower boundary
+ * @param $field string Field name
+ * @param $dir string If 'newer', sort in ascending order, otherwise
+ * sort in descending order
+ * @param $start string Value to start the list at. If $dir == 'newer'
+ * this is the lower boundary, otherwise it's the upper boundary
+ * @param $end string Value to end the list at. If $dir == 'newer' this
+ * is the upper boundary, otherwise it's the lower boundary
*/
protected function addWhereRange($field, $dir, $start, $end) {
$isDirNewer = ($dir === 'newer');
}
/**
- * Add an option such as LIMIT or USE INDEX
- * @param string $name Option name
- * @param string $value Option value
+ * Add an option such as LIMIT or USE INDEX. If an option was set
+ * before, the old value will be overwritten
+ * @param $name string Option name
+ * @param $value string Option value
*/
protected function addOption($name, $value = null) {
if (is_null($value))
/**
* Execute a SELECT query based on the values in the internal arrays
- * @param string $method Function the query should be attributed to. You should usually use __METHOD__ here
+ * @param $method string Function the query should be attributed to.
+ * You should usually use __METHOD__ here
* @return ResultWrapper
*/
protected function select($method) {
}
/**
- * Add information (title and namespace) about a Title object to a result array
- * @param array $arr Result array à la ApiResult
- * @param Title $title Title object
- * @param string $prefix Module prefix
+ * Add information (title and namespace) about a Title object to a
+ * result array
+ * @param $arr array Result array à la ApiResult
+ * @param $title Title
+ * @param $prefix string Module prefix
*/
public static function addTitleInfo(&$arr, $title, $prefix='') {
$arr[$prefix . 'ns'] = intval($title->getNamespace());
/**
* Override this method to request extra fields from the pageSet
* using $pageSet->requestField('fieldName')
- * @param ApiPageSet $pageSet
+ * @param $pageSet ApiPageSet
*/
public function requestExtraData($pageSet) {
}
/**
* Add a sub-element under the page element with the given page ID
- * @param int $pageId Page ID
- * @param array $data Data array à la ApiResult
+ * @param $pageId int Page ID
+ * @param $data array Data array à la ApiResult
* @return bool Whether the element fit in the result
*/
protected function addPageSubItems($pageId, $data) {
}
/**
- * Same as addPageSubItems(), but one element of $data
- * at a time
- * @param int $pageId Page ID
- * @param array $data Data array à la ApiResult
- * @param string $elemname XML element name. If null, getModuleName() is used
+ * Same as addPageSubItems(), but one element of $data at a time
+ * @param $pageId int Page ID
+ * @param $data array Data array à la ApiResult
+ * @param $elemname string XML element name. If null, getModuleName()
+ * is used
* @return bool Whether the element fit in the result
*/
protected function addPageSubItem($pageId, $item, $elemname = null) {
/**
* Set a query-continue value
- * @param $paramName Parameter name
- * @param $paramValue Parameter value
+ * @param $paramName string Parameter name
+ * @param $paramValue string Parameter value
*/
protected function setContinueEnumParameter($paramName, $paramValue) {
$paramName = $this->encodeParamName($paramName);
}
/**
- * Get the Query database connection (readonly)
+ * Get the Query database connection (read-only)
* @return Database
*/
protected function getDB() {
/**
* Selects the query database connection with the given name.
- * If no such connection has been requested before, it will be created.
- * Subsequent calls with the same $name will return the same connection
- * as the first, regardless of $db or $groups new values.
- * @param string $name Name to assign to the database connection
- * @param int $db One of the DB_* constants
- * @param array $groups Query groups
+ * See ApiQuery::getNamedDB() for more information
+ * @param $name string Name to assign to the database connection
+ * @param $db int One of the DB_* constants
+ * @param $groups array Query groups
* @return Database
*/
public function selectNamedDB($name, $db, $groups) {
/**
* Convert a title to a DB key
- * @param string $title Page title with spaces
+ * @param $title string Page title with spaces
* @return string Page title with underscores
*/
public function titleToKey($title) {
/**
* The inverse of titleToKey()
- * @param string $key Page title with underscores
+ * @param $key string Page title with underscores
* @return string Page title with spaces
*/
public function keyToTitle($key) {
/**
* An alternative to titleToKey() that doesn't trim trailing spaces
- * @param string $titlePart Title part with spaces
+ * @param $titlePart string Title part with spaces
* @return string Title part with underscores
*/
public function titlePartToKey($titlePart) {
/**
* An alternative to keyToTitle() that doesn't trim trailing spaces
- * @param string $keyPart Key part with spaces
+ * @param $keyPart string Key part with spaces
* @return string Key part with underscores
*/
public function keyPartToTitle($keyPart) {
/**
* Overrides base class to prepend 'g' to every generator parameter
+ * @param $paramNames string Parameter name
+ * @return string Prefixed parameter name
*/
public function encodeParamName($paramName) {
if ($this->mIsGenerator)
/**
* Execute this module as a generator
- * @param $resultPageSet PageSet: All output should be appended to this object
+ * @param $resultPageSet ApiPageSet: All output should be appended to
+ * this object
*/
public abstract function executeGenerator($resultPageSet);
}
dépôts / lhc / web / wiklou.git / commitdiff