From 10f21e1f414dfd9a369df8b1c71aa2e099fca9f2 Mon Sep 17 00:00:00 2001
From: Evan Prodromou <evan@status.net>
Date: Wed, 20 Jan 2010 16:37:41 -0500
Subject: [PATCH] add class and function doc comments to PuSH plugin

---
 plugins/PubSubHubBub/PubSubHubBubPlugin.php | 85 +++++++++++++++++++++
 1 file changed, 85 insertions(+)

diff --git a/plugins/PubSubHubBub/PubSubHubBubPlugin.php b/plugins/PubSubHubBub/PubSubHubBubPlugin.php
index c4af2c854b..8286cd5489 100644
--- a/plugins/PubSubHubBub/PubSubHubBubPlugin.php
+++ b/plugins/PubSubHubBub/PubSubHubBubPlugin.php
@@ -35,27 +35,99 @@ define('DEFAULT_HUB', 'http://pubsubhubbub.appspot.com');
 
 require_once INSTALLDIR.'/plugins/PubSubHubBub/publisher.php';
 
+/**
+ * Plugin to provide publisher side of PubSubHubBub (PuSH)
+ * relationship.
+ *
+ * PuSH is a real-time or near-real-time protocol for Atom
+ * and RSS feeds. More information here:
+ *
+ * http://code.google.com/p/pubsubhubbub/
+ *
+ * To enable, add the following line to your config.php:
+ *
+ * addPlugin('PubSubHubBub');
+ *
+ * This will use the Google default hub. If you'd like to use
+ * another, try:
+ *
+ * addPlugin('PubSubHubBub',
+ *           array('hub' => 'http://yourhub.example.net/'));
+ *
+ * @category  Plugin
+ * @package   StatusNet
+ * @author    Craig Andrews <candrews@integralblue.com>
+ * @copyright 2009 Craig Andrews http://candrews.integralblue.com
+ * @license   http://www.fsf.org/licensing/licenses/agpl-3.0.html AGPLv3
+ * @link      http://status.net/
+ */
+
 class PubSubHubBubPlugin extends Plugin
 {
+    /**
+     * URL of the hub to advertise and publish to.
+     */
+
     public $hub = DEFAULT_HUB;
 
+    /**
+     * Default constructor.
+     */
+
     function __construct()
     {
         parent::__construct();
     }
 
+    /**
+     * Hooks the StartApiAtom event
+     *
+     * Adds the necessary bits to advertise PubSubHubBub
+     * for the Atom feed.
+     *
+     * @param Action $action The API action being shown.
+     *
+     * @return boolean hook value
+     */
+
     function onStartApiAtom($action)
     {
         $action->element('link', array('rel' => 'hub', 'href' => $this->hub), null);
+
+        return true;
     }
 
+    /**
+     * Hooks the StartApiRss event
+     *
+     * Adds the necessary bits to advertise PubSubHubBub
+     * for the RSS 2.0 feeds.
+     *
+     * @param Action $action The API action being shown.
+     *
+     * @return boolean hook value
+     */
+
     function onStartApiRss($action)
     {
         $action->element('atom:link', array('rel' => 'hub',
                                             'href' => $this->hub),
                          null);
+        return true;
     }
 
+    /**
+     * Hook for a queued notice.
+     *
+     * When a notice has been queued, will ping the
+     * PuSH hub for each Atom and RSS feed in which
+     * the notice appears.
+     *
+     * @param Notice $notice The notice that's been queued
+     *
+     * @return boolean hook value
+     */
+
     function onHandleQueuedNotice($notice)
     {
         $publisher = new Publisher($this->hub);
@@ -147,8 +219,21 @@ class PubSubHubBubPlugin extends Plugin
                                 $this->hub.':'.$publisher->last_response());
             }
         }
+
+        return true;
     }
 
+    /**
+     * Provide version information
+     *
+     * Adds this plugin's version data to the global
+     * version array, for e.g. displaying on the version page.
+     *
+     * @param array &$versions array of array of versions
+     *
+     * @return boolean hook value
+     */
+
     function onPluginVersion(&$versions)
     {
         $versions[] = array('name' => 'PubSubHubBub',