From: Roan Kattouw Date: Fri, 13 Feb 2009 14:13:03 +0000 (+0000) Subject: API: More docs, break long lines in docs X-Git-Tag: 1.31.0-rc.0~42910 X-Git-Url: http://git.cyclocoop.org/%22%20.%20generer_url_ecrire%28%22articles%22%2C%22id_article=%24id_article%22%29%20.%20%22?a=commitdiff_plain;h=7526c937c71aa3eb51e70c9fdf058a5669eb413b;p=lhc%2Fweb%2Fwiklou.git API: More docs, break long lines in docs --- diff --git a/includes/api/ApiFormatBase.php b/includes/api/ApiFormatBase.php index fc5ac51c51..deab8e3021 100644 --- a/includes/api/ApiFormatBase.php +++ b/includes/api/ApiFormatBase.php @@ -38,9 +38,11 @@ abstract class ApiFormatBase extends ApiBase { 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); @@ -61,9 +63,8 @@ abstract class ApiFormatBase extends ApiBase { 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; @@ -71,36 +72,40 @@ abstract class ApiFormatBase extends ApiBase { /** * 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 &quot; 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(); @@ -167,8 +172,10 @@ See complete documentation, or } /** - * 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()) @@ -188,15 +195,18 @@ See complete documentation, or } /** - * 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; @@ -229,9 +239,6 @@ See complete documentation, or return $text; } - /** - * Returns usage examples for this format. - */ protected function getExamples() { return 'api.php?action=query&meta=siteinfo&siprop=namespaces&format=' . $this->getModuleName(); } @@ -256,7 +263,10 @@ class ApiFormatFeedWrapper extends ApiFormatBase { } /** - * 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. diff --git a/includes/api/ApiQuery.php b/includes/api/ApiQuery.php index 468d350505..aecda00d1a 100644 --- a/includes/api/ApiQuery.php +++ b/includes/api/ApiQuery.php @@ -29,13 +29,13 @@ if (!defined('MEDIAWIKI')) { } /** - * 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 */ @@ -111,6 +111,8 @@ class ApiQuery extends ApiBase { /** * 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 )) { @@ -122,6 +124,7 @@ class ApiQuery extends ApiBase { /** * Gets a default slave database connection object + * @return Database */ public function getDB() { if (!isset ($this->mSlaveDB)) { @@ -136,7 +139,11 @@ class ApiQuery extends ApiBase { * 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)) { @@ -149,6 +156,7 @@ class ApiQuery extends ApiBase { /** * Gets the set of pages the user has requested (or generated) + * @return ApiPageSet */ public function getPageSet() { return $this->mPageSet; @@ -156,6 +164,7 @@ class ApiQuery extends ApiBase { /** * Get the array mapping module names to class names + * @return array(modulename => classname) */ function getModules() { return array_merge($this->mQueryPropModules, $this->mQueryListModules, $this->mQueryMetaModules); @@ -172,7 +181,7 @@ class ApiQuery extends ApiBase { /** * 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. @@ -228,6 +237,8 @@ class ApiQuery extends ApiBase { * 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. @@ -238,6 +249,9 @@ class ApiQuery extends ApiBase { /** * 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]; @@ -247,8 +261,9 @@ class ApiQuery extends ApiBase { } /** - * 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() { @@ -392,7 +407,10 @@ class ApiQuery extends ApiBase { } /** - * 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) { @@ -433,10 +451,6 @@ class ApiQuery extends ApiBase { $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 ( @@ -463,6 +477,7 @@ class ApiQuery extends ApiBase { /** * Override the parent to generate help messages for all available query modules. + * @return string */ public function makeHelpMsg() { @@ -493,10 +508,13 @@ class ApiQuery extends ApiBase { /** * 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); @@ -509,14 +527,15 @@ class ApiQuery extends ApiBase { $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); diff --git a/includes/api/ApiQueryBase.php b/includes/api/ApiQueryBase.php index 73f70ebecb..f7413c24d4 100644 --- a/includes/api/ApiQueryBase.php +++ b/includes/api/ApiQueryBase.php @@ -30,7 +30,8 @@ if (!defined('MEDIAWIKI')) { /** * 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 */ @@ -58,8 +59,9 @@ abstract class ApiQueryBase extends ApiBase { /** * 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)) { @@ -75,8 +77,8 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -86,9 +88,11 @@ abstract class ApiQueryBase extends ApiBase { /** * 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)) @@ -98,7 +102,7 @@ abstract class ApiQueryBase extends ApiBase { /** * 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)) @@ -109,8 +113,8 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -130,7 +134,7 @@ abstract class ApiQueryBase extends ApiBase { * * 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)) { @@ -145,8 +149,8 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -159,8 +163,8 @@ abstract class ApiQueryBase extends ApiBase { /** * 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 @@ -172,10 +176,13 @@ abstract class ApiQueryBase extends ApiBase { /** * 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'); @@ -197,9 +204,10 @@ abstract class ApiQueryBase extends ApiBase { } /** - * 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)) @@ -210,7 +218,8 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -243,10 +252,11 @@ abstract class ApiQueryBase extends ApiBase { } /** - * 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()); @@ -256,7 +266,7 @@ abstract class ApiQueryBase extends ApiBase { /** * Override this method to request extra fields from the pageSet * using $pageSet->requestField('fieldName') - * @param ApiPageSet $pageSet + * @param $pageSet ApiPageSet */ public function requestExtraData($pageSet) { } @@ -271,8 +281,8 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -284,11 +294,11 @@ abstract class ApiQueryBase extends ApiBase { } /** - * 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) { @@ -306,8 +316,8 @@ abstract class ApiQueryBase extends ApiBase { /** * 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); @@ -318,7 +328,7 @@ abstract class ApiQueryBase extends ApiBase { } /** - * Get the Query database connection (readonly) + * Get the Query database connection (read-only) * @return Database */ protected function getDB() { @@ -329,12 +339,10 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -351,7 +359,7 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -366,7 +374,7 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -382,7 +390,7 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -391,7 +399,7 @@ abstract class ApiQueryBase extends ApiBase { /** * 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) { @@ -429,6 +437,8 @@ abstract class ApiQueryGeneratorBase extends ApiQueryBase { /** * 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) @@ -439,7 +449,8 @@ abstract class ApiQueryGeneratorBase extends ApiQueryBase { /** * 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); }