API: Add a little docu so that we might be able to make some sense of how this works ;)

diff --git a/includes/api/ApiQueryRecentChanges.php b/includes/api/ApiQueryRecentChanges.php
index 2268a8f..6809840 100644 (file)
--- a/includes/api/ApiQueryRecentChanges.php
+++ b/includes/api/ApiQueryRecentChanges.php
@@ -44,10 +44,21 @@ class ApiQueryRecentChanges extends ApiQueryBase {
                        $fld_timestamp = false, $fld_title = false, $fld_ids = false,
                        $fld_sizes = false;
         
+       /**
+        * Generates and outputs the result of this query based upon the provided parameters.
+        */
        public function execute() {
+               /* Initialize vars */
                $limit = $prop = $namespace = $show = $dir = $start = $end = null;
+               
+               /* Get the parameters of the request. */
                extract($this->extractRequestParams());
 
+               /* Build our basic query. Namely, something along the lines of:
+                * SELECT * from recentchanges WHERE rc_timestamp > $start 
+                *              AND rc_timestamp < $end AND rc_namespace = $namespace 
+                *              AND rc_deleted = '0'
+                */
                $this->addTables('recentchanges');
                $this->addWhereRange('rc_timestamp', $dir, $start, $end);
                $this->addWhereFld('rc_namespace', $namespace);
@@ -55,9 +66,16 @@ class ApiQueryRecentChanges extends ApiQueryBase {
 
                if (!is_null($show)) {
                        $show = array_flip($show);
-                       if ((isset ($show['minor']) && isset ($show['!minor'])) || (isset ($show['bot']) && isset ($show['!bot'])) || (isset ($show['anon']) && isset ($show['!anon'])))
+
+                       /* Check for conflicting parameters. */
+                       if ((isset ($show['minor']) && isset ($show['!minor'])) 
+                                       || (isset ($show['bot']) && isset ($show['!bot'])) 
+                                       || (isset ($show['anon']) && isset ($show['!anon']))) {
+                                               
                                $this->dieUsage("Incorrect parameter - mutually exclusive values may not be supplied", 'show');
+                       }
 
+                       /* Add additional conditions to query depending upon parameters. */
                        $this->addWhereIf('rc_minor = 0', isset ($show['!minor']));
                        $this->addWhereIf('rc_minor != 0', isset ($show['minor']));
                        $this->addWhereIf('rc_bot = 0', isset ($show['!bot']));
@@ -66,6 +84,7 @@ class ApiQueryRecentChanges extends ApiQueryBase {
                        $this->addWhereIf('rc_user != 0', isset ($show['!anon']));
                }
 
+               /* Add the fields we're concerned with to out query. */
                $this->addFields(array (
                        'rc_timestamp',
                        'rc_namespace',
@@ -75,9 +94,11 @@ class ApiQueryRecentChanges extends ApiQueryBase {
                        'rc_moved_to_title'
                ));
 
+               /* Determine what properties we need to display. */
                if (!is_null($prop)) {
                        $prop = array_flip($prop);
 
+                       /* Set up internal members based upon params. */
                        $this->fld_comment = isset ($prop['comment']);
                        $this->fld_user = isset ($prop['user']);
                        $this->fld_flags = isset ($prop['flags']);
@@ -85,7 +106,8 @@ class ApiQueryRecentChanges extends ApiQueryBase {
                        $this->fld_title = isset ($prop['title']);
                        $this->fld_ids = isset ($prop['ids']);
                        $this->fld_sizes = isset ($prop['sizes']);
-                        
+
+                       /* Add fields to our query if they are specified as a needed parameter. */
                        $this->addFieldsIf('rc_id', $this->fld_ids);                    
                        $this->addFieldsIf('rc_cur_id', $this->fld_ids);                        
                        $this->addFieldsIf('rc_this_oldid', $this->fld_ids);                    
@@ -100,14 +122,21 @@ class ApiQueryRecentChanges extends ApiQueryBase {
                        $this->addFieldsIf('rc_new_len', $this->fld_sizes);
                }
 
+               /* Specify the limit for our query. It's $limit+1 because we (possibly) need to 
+                * generate a "continue" parameter, to allow paging. */
                $this->addOption('LIMIT', $limit +1);
+
+               /* Specify the index to use in the query as rc_timestamp, instead of rc_revid (default). */
                $this->addOption('USE INDEX', 'rc_timestamp');
 
                $data = array ();
                $count = 0;
+
+               /* Perform the actual query. */
                $db = $this->getDB();
                $res = $this->select(__METHOD__);
-               
+
+               /* Iterate through the rows, adding data extracted from them to our query result. */
                while ($row = $db->fetchObject($res)) {
                        if (++ $count > $limit) {
                                // We've reached the one extra which shows that there are additional pages to be had. Stop here...
@@ -115,23 +144,39 @@ class ApiQueryRecentChanges extends ApiQueryBase {
                                break;
                        }
 
+                       /* Extract the data from a single row. */
                        $vals = $this->extractRowInfo($row);
+                       
+                       /* Add that row's data to our final output. */
                        if($vals)
                                $data[] = $vals;
                }
+
                $db->freeResult($res);
 
+               /* Format the result */
                $result = $this->getResult();
                $result->setIndexedTagName($data, 'rc');
                $result->addValue('query', $this->getModuleName(), $data);
        }
 
+       /**
+        * Extracts from a single sql row the data needed to describe one recent change.
+        *
+        * @param $row The row from which to extract the data.
+        * @return An array mapping strings (descriptors) to their respective string values.
+        * @access private
+        */
        private function extractRowInfo($row) {
+               /* If page was moved somewhere, get the title of the move target. */
                $movedToTitle = false;
                if (!empty($row->rc_moved_to_title))
                        $movedToTitle = Title :: makeTitle($row->rc_moved_to_ns, $row->rc_moved_to_title);
 
+               /* Determine the title of the page that has been changed. */
                $title = Title :: makeTitle($row->rc_namespace, $row->rc_title);
+
+               /* Our output data. */
                $vals = array ();
 
                $type = intval ( $row->rc_type );
@@ -146,12 +191,14 @@ class ApiQueryRecentChanges extends ApiQueryBase {
                default: $vals['type'] = $type;
                }
 
+               /* Create a new entry in the result for the title. */
                if ($this->fld_title) {
                        ApiQueryBase :: addTitleInfo($vals, $title);
                        if ($movedToTitle)
                                ApiQueryBase :: addTitleInfo($vals, $movedToTitle, "new_");
                }
 
+               /* Add ids, such as rcid, pageid, revid, and oldid to the change's info. */
                if ($this->fld_ids) {
                        $vals['rcid'] = intval($row->rc_id);
                        $vals['pageid'] = intval($row->rc_cur_id);
@@ -159,12 +206,14 @@ class ApiQueryRecentChanges extends ApiQueryBase {
                        $vals['old_revid'] = intval( $row->rc_last_oldid );
                }
 
+               /* Add user data and 'anon' flag, if use is anonymous. */
                if ($this->fld_user) {
                        $vals['user'] = $row->rc_user_text;
                        if(!$row->rc_user)
                                $vals['anon'] = '';
                }
 
+               /* Add flags, such as new, minor, bot. */
                if ($this->fld_flags) {
                        if ($row->rc_bot)
                                $vals['bot'] = '';
@@ -174,14 +223,17 @@ class ApiQueryRecentChanges extends ApiQueryBase {
                                $vals['minor'] = '';
                }
 
+               /* Add sizes of each revision. (Only available on 1.10+) */
                if ($this->fld_sizes) {
                        $vals['oldlen'] = intval($row->rc_old_len);
                        $vals['newlen'] = intval($row->rc_new_len);
                }
-               
+
+               /* Add the timestamp. */
                if ($this->fld_timestamp)
                        $vals['timestamp'] = wfTimestamp(TS_ISO_8601, $row->rc_timestamp);
 
+               /* Add edit summary / log summary. */
                if ($this->fld_comment && !empty ($row->rc_comment)) {
                        $vals['comment'] = $row->rc_comment;
                }