Merge branch '0.9.x' into facebook-app-plugin

lib/default.php

@@ -145,16 +145,16 @@ $default =
         'integration' =>
         array('source' => 'StatusNet', # source attribute for Twitter
               'taguri' => $_server.',2009'), # base for tag URIs
-	'twitter' =>
-	array('enabled'       => true,
-	    'consumer_key'    => null,
-	    'consumer_secret' => null),
+        'twitter' =>
+        array('enabled'       => true,
+              'consumer_key'    => null,
+              'consumer_secret' => null),
         'memcached' =>
         array('enabled' => false,
               'server' => 'localhost',
               'base' => null,
               'port' => 11211),
- 		'ping' =>
+        'ping' =>
         array('notify' => array()),
         'inboxes' =>
         array('enabled' => true), # ignored after 0.9.x
@@ -200,12 +200,12 @@ $default =
                                    'video/mp4',
                                    'video/quicktime',
                                    'video/mpeg'),
-        'file_quota' => 5000000,
-        'user_quota' => 50000000,
-        'monthly_quota' => 15000000,
-        'uploads' => true,
-        'filecommand' => '/usr/bin/file',
-        ),
+              'file_quota' => 5000000,
+              'user_quota' => 50000000,
+              'monthly_quota' => 15000000,
+              'uploads' => true,
+              'filecommand' => '/usr/bin/file',
+              ),
         'group' =>
         array('maxaliases' => 3,
               'desclimit' => null),

lib/httpclient.php

@@ -48,7 +48,7 @@ if (!defined('STATUSNET')) {
 class HTTPResponse
 {
     public $code = null;
-    public $headers = null;
+    public $headers = array();
     public $body = null;
 }
 

lib/queuehandler.php

@@ -27,6 +27,22 @@ define('CLAIM_TIMEOUT', 1200);
 define('QUEUE_HANDLER_MISS_IDLE', 10);
 define('QUEUE_HANDLER_HIT_IDLE', 0);
 
+/**
+ * Base class for queue handlers.
+ *
+ * As extensions of the Daemon class, each queue handler has the ability
+ * to launch itself in the background, at which point it'll pass control
+ * to the configured QueueManager class to poll for updates.
+ *
+ * Subclasses must override at least the following methods:
+ * - transport
+ * - start
+ * - finish
+ * - handle_notice
+ *
+ * Some subclasses will also want to override the idle handler:
+ * - idle
+ */
 class QueueHandler extends Daemon
 {
 
@@ -39,6 +55,14 @@ class QueueHandler extends Daemon
         }
     }
 
+    /**
+     * How many seconds a polling-based queue manager should wait between
+     * checks for new items to handle.
+     *
+     * Defaults to 60 seconds; override to speed up or slow down.
+     *
+     * @return int timeout in seconds
+     */
     function timeout()
     {
         return 60;
@@ -54,24 +78,69 @@ class QueueHandler extends Daemon
         return strtolower($this->class_name().'.'.$this->get_id());
     }
 
+    /**
+     * Return transport keyword which identifies items this queue handler
+     * services; must be defined for all subclasses.
+     *
+     * Must be 8 characters or less to fit in the queue_item database.
+     * ex "email", "jabber", "sms", "irc", ...
+     *
+     * @return string
+     */
     function transport()
     {
         return null;
     }
 
+    /**
+     * Initialization, run when the queue handler starts.
+     * If this function indicates failure, the handler run will be aborted.
+     *
+     * @fixme run() will abort if this doesn't return true,
+     *        but some subclasses don't bother.
+     * @return boolean true on success, false on failure
+     */
     function start()
     {
     }
 
+    /**
+     * Cleanup, run when the queue handler ends.
+     * If this function indicates failure, a warning will be logged.
+     *
+     * @fixme run() will throw warnings if this doesn't return true,
+     *        but many subclasses don't bother.
+     * @return boolean true on success, false on failure
+     */
     function finish()
     {
     }
 
+    /**
+     * Here's the meat of your queue handler -- you're handed a Notice
+     * object, which you may do as you will with.
+     *
+     * If this function indicates failure, a warning will be logged
+     * and the item is placed back in the queue to be re-run.
+     *
+     * @param Notice $notice
+     * @return boolean true on success, false on failure
+     */
     function handle_notice($notice)
     {
         return true;
     }
 
+    /**
+     * Setup and start of run loop for this queue handler as a daemon.
+     * Most of the heavy lifting is passed on to the QueueManager's service()
+     * method, which passes control back to our handle_notice() method for
+     * each notice that comes in on the queue.
+     *
+     * Most of the time this won't need to be overridden in a subclass.
+     *
+     * @return boolean true on success, false on failure
+     */
     function run()
     {
         if (!$this->start()) {
@@ -100,6 +169,14 @@ class QueueHandler extends Daemon
         return true;
     }
 
+    /**
+     * Called by QueueHandler after each handled item or empty polling cycle.
+     * This is a good time to e.g. service your XMPP connection.
+     *
+     * Doesn't need to be overridden if there's no maintenance to do.
+     *
+     * @param int $timeout seconds to sleep if there's nothing to do
+     */
     function idle($timeout=0)
     {
         if ($timeout > 0) {