Nik has submitted this change and it was merged.

Change subject: Added documentation.
......................................................................


Added documentation.

Change-Id: I53582bcb41fd82485f803422ccf3c1774c0af7a9
---
M PubSubHubbub.body.php
M tests/phpunit/PubSubHubbubTest.php
2 files changed, 171 insertions(+), 46 deletions(-)

Approvals:
  Nik: Looks good to me, approved
  WikidataJenkins: Verified



diff --git a/PubSubHubbub.body.php b/PubSubHubbub.body.php
index f744b11..fd7c4f6 100644
--- a/PubSubHubbub.body.php
+++ b/PubSubHubbub.body.php
@@ -24,18 +24,57 @@
 
 namespace PubSubHubbub;
 
+use Article;
+use Content;
+use JobQueueGroup;
+use OutputPage;
+use Page;
+use RawPage;
+use Revision;
+use Status;
+use Title;
+use User;
+use Wikibase\NamespaceUtils;
+use WikiPage;
+
+/**
+ * The main implementation of the PubSubHubbub extension.
+ *
+ * @licence GNU GPL v2+
+ * @author Sebastian Brückner < [email protected] 
>
+ * @author Alexander Lehmann < [email protected] >
+ */
 class PubSubHubbub {
 
-       public static function onPageContentSaveComplete( $article, $user, 
$content, $summary,
-                       $isMinor, $section, $flags, $revision, $status, 
$baseRevId ) {
+       /**
+        * Hook executed after an article has been updated.
+        * Creates a {@link PublishChangesJob} that publishes that change to 
the defined hub and adds it to the job queue.
+        *
+        * @see 
https://www.mediawiki.org/wiki/Manual:Hooks/PageContentSaveComplete
+        *
+        * @param Page $article WikiPage modified.
+        * @param User $user User performing the modification.
+        * @param Content $content New content.
+        * @param string $summary  Edit summary/comment.
+        * @param boolean $isMinor Whether or not the edit was marked as minor.
+        * @param boolean $isWatch (No longer used.)
+        * @param integer $section (No longer used.)
+        * @param integer $flags Flags passed to 
<code>WikiPage::doEditContent()</code>.
+        * @param Revision|null $revision New Revision of the article (can be 
null for edits that change nothing).
+        * @param Status $status Status object about to be returned by 
<code>doEditContent()</code>.
+        * @param integer $baseRevId The rev ID (or false) this edit was based 
on.
+        * @return bool whether to continue hook processing. This 
implementation always returns <code>true</code>.
+        */
+       public static function onPageContentSaveComplete( Page $article, User 
$user, $content, $summary, $isMinor,
+               $isWatch, $section, $flags, $revision, Status $status, 
$baseRevId ) {
                if ( !self::isConfigurationSetUp() ) {
                        return true;
                }
-               if ( $baseRevId && !is_null( $baseRevId->value['revision'] ) ) {
+               if ( !is_null( $revision ) ) {
                        $jobParams = array();
                        $title = $article->getTitle();
                        $job = new PublishChangesJob( $title, $jobParams );
-                       $jobQueueGroup = \JobQueueGroup::singleton()->push( 
$job );
+                       $jobQueueGroup = JobQueueGroup::singleton()->push( $job 
);
                        if ( !$jobQueueGroup ) {
                                wfLogWarning( "Failed to acquire a 
JobQueueGroup for $job" );
                        }
@@ -43,11 +82,17 @@
                return true;
        }
 
-       public static function getPageURL( $title ) {
+       /**
+        * Create the resource URL for a given {@link Title}.
+        *
+        * @param Title $title The {@link Title} to generate a resource URL for.
+        * @return string the generated resource URL.
+        */
+       public static function getPageURL( Title $title ) {
                if ( defined( 'WB_VERSION' ) ) {
                        // Wikibase extension is installed
-                       if ( \Wikibase\NamespaceUtils::isEntityNamespace( 
$title->getNamespace() ) ) {
-                               $specialTitle = \Title::makeTitle( -1, 
'EntityData' );
+                       if ( NamespaceUtils::isEntityNamespace( 
$title->getNamespace() ) ) {
+                               $specialTitle = Title::makeTitle( -1, 
'EntityData' );
                                return $specialTitle->getCanonicalURL() . "/" . 
$title->getBaseText() . '.json';
                        }
                }
@@ -57,6 +102,11 @@
                ) );
        }
 
+       /**
+        * Insert an HTTP Link header to the current response.
+        *
+        * @param Article|WikiPage|RawPage $page The resource.
+        */
        public static function insertLinkHeader( $page ) {
                global $wgRequest, $wgPubSubHubbubHubURL;
                if ( !self::isConfigurationSetUp() ) {
@@ -65,6 +115,11 @@
                $wgRequest->response()->header( self::createLinkHeader( 
$wgPubSubHubbubHubURL, $page ), false );
        }
 
+       /**
+        * Check whether the extension is properly configured.
+        *
+        * @return bool whether there's a PubSubHubbub hub URL set up in the 
LocalSettings.
+        */
        public static function isConfigurationSetUp() {
                global $wgPubSubHubbubHubURL;
                if( !isset( $wgPubSubHubbubHubURL ) ) {
@@ -74,23 +129,62 @@
                return true;
        }
 
+       /**
+        * Create an HTTP Link header for the given hub and resource.
+        *
+        * @param string $hubURL The URL of the hub to point to.
+        * @param Article|WikiPage|RawPage $page The resource.
+        * @return string the HTTP Link header.
+        */
        public static function createLinkHeader( $hubURL, $page ) {
                return "Link: <" . $hubURL . ">; rel=\"hub\", <"
-                       . self::getPageURL( $page->getTitle() ) . ">; 
rel=\"self\"";
+               . self::getPageURL( $page->getTitle() ) . ">; rel=\"self\"";
        }
 
-       public static function onRawPageViewBeforeOutput( $rawPage, $text ) {
+       /**
+        * Called before displaying a page with <code>action=raw</code>.
+        * Add HTTP Link headers.
+        *
+        * @see 
https://www.mediawiki.org/wiki/Manual:Hooks/RawPageViewBeforeOutput
+        *
+        * @param RawPage $rawPage The {@link RawPage} object.
+        * @param string $text The text that's going to be the output.
+        * @return bool whether display is allowed. This implementation always 
returns <code>true</code>.
+        */
+       public static function onRawPageViewBeforeOutput( RawPage $rawPage, 
$text ) {
                self::insertLinkHeader( $rawPage );
+               return true;
        }
 
-       public static function onOutputPageBeforeHTML( \OutputPage &$out, 
&$text ) {
+       /**
+        * A page has been processed by the parser and the resulting HTML is 
about to be displayed.
+        * Add HTTP Link headers.
+        *
+        * @see https://www.mediawiki.org/wiki/Manual:Hooks/OutputPageBeforeHTML
+        *
+        * @param OutputPage $out
+        * @param string $text The text that will be displayed, in HTML.
+        * @return OutputPage <code>$out</code>
+        */
+       public static function onOutputPageBeforeHTML( OutputPage &$out, &$text 
) {
                if ( $out->canUseWikiPage() ) {
                        self::insertLinkHeader( $out->getWikiPage() );
                }
+               return $out;
        }
 
+       /**
+        * Called when building a list of files with PHPUnit tests.
+        * Add our tests to the list of PHPUnit test files.
+        *
+        * @see https://www.mediawiki.org/wiki/Manual:Hooks/UnitTestsList
+        *
+        * @param string[] $files The list of test files.
+        * @return bool
+        */
        public static function onUnitTestsList( &$files ) {
                $files = array_merge( $files, glob( __DIR__ . 
'/tests/phpunit/*Test.php' ) );
                return true;
        }
+
 }
diff --git a/tests/phpunit/PubSubHubbubTest.php 
b/tests/phpunit/PubSubHubbubTest.php
index e0a73e1..52bf0b5 100644
--- a/tests/phpunit/PubSubHubbubTest.php
+++ b/tests/phpunit/PubSubHubbubTest.php
@@ -2,6 +2,13 @@
 
 namespace PubSubHubbub;
 
+use Article;
+use Language;
+use MediaWikiLangTestCase;
+use Revision;
+use Title;
+use Wikibase\NamespaceUtils;
+
 /**
  * @covers PubSubHubbub\PubSubHubbub
  *
@@ -9,17 +16,19 @@
  * @group PubSubHubbub
  *
  * @licence GNU GPL v2+
- * @author Alexander Lehmann
+ * @author Alexander Lehmann < [email protected] >
+ * @author Sebastian Brückner < [email protected] 
>
  */
-class PubSubHubbubTest extends \MediaWikiLangTestCase {
+class PubSubHubbubTest extends MediaWikiLangTestCase {
 
        protected function setUp() {
                parent::setUp();
                $this->setMwGlobals( array(
-                       'wgContLang' => \Language::factory( 'en' ),
+                       'wgContLang' => Language::factory( 'en' ),
                        'wgLanguageCode' => 'en',
-                       'wgPubSubHubbubHubURL' => 'https://www.example.com',
                ) );
+               global $wgPubSubHubbubHubURL;
+               $wgPubSubHubbubHubURL = 'https://www.example.com';
        }
 
        protected function tearDown() {
@@ -29,34 +38,33 @@
        /**
         * @dataProvider configData
         *
-        * @param $HubURL
+        * @param string $HubURL URL of the PubSubHubbub Hub.
         */
        public function testIsConfigurationSetUp( $HubURL ) {
                global $wgPubSubHubbubHubURL;
-               $this->setMwGlobals( array(
-                       'wgPubSubHubbubHubURL' => $HubURL,
-               ) );
+               $wgPubSubHubbubHubURL = $HubURL;
                $this->assertEquals( isset( $wgPubSubHubbubHubURL ), 
PubSubHubbub::isConfigurationSetUp() );
        }
 
        /**
         * @dataProvider contentSaveData
         *
-        * @param $article WikiPage modified
-        * @param $baseRevId the rev ID (or false) this edit was based on
-        * @param int $count
+        * @param Article $article The modified Article from the Edit.
+        * @param Revision|null $revision The revision (or null) the edit was 
based on.
+        * @param int $count The expected number of jobs in the database.
         */
-       public function testOnPageContentSaveComplete( $article, $baseRevId, 
$count ) {
+       public function testOnPageContentSaveComplete( Article $article, 
$revision, $count ) {
                $user = $this->getMock( 'User' );
                $content = $this->getMock ( 'Content' );
                $summary = '';
                $isMinor = false;
+               $isWatch = false;
                $section = null;
                $flags = null;
-               $revision = 2;
                $status = $this->getMock ( 'Status' );
+               $baseRevId = 1;
 
-               PubSubHubbub::onPageContentSaveComplete( $article, $user, 
$content, $summary, $isMinor,
+               PubSubHubbub::onPageContentSaveComplete( $article, $user, 
$content, $summary, $isMinor, $isWatch,
                        $section, $flags, $revision, $status, $baseRevId );
                $row = array( array( $count ) );
                $this->assertSelect( "job", "count(*)", "", $row );
@@ -65,13 +73,13 @@
        /**
         * @dataProvider linkHeaderData
         *
-        * @param string $titleText
-        * @param string $urlText
+        * @param string $titleText Text to use for the title.
+        * @param string $urlText Text to identify a title in a URL.
         */
        public function testCreateLinkHeader( $titleText, $urlText) {
                global $wgScript, $wgServer, $wgPubSubHubbubHubURL;
-               $title = \Title::newFromText( $titleText );
-               $article = new \Article( $title );
+               $title = Title::newFromText( $titleText );
+               $article = new Article( $title );
 
                $titleURL = $wgServer . $wgScript . "?title=" . $urlText . 
"&action=raw";
                $linkHeader = "Link: <" . $wgPubSubHubbubHubURL . ">; 
rel=\"hub\", <" . $titleURL . ">; rel=\"self\"";
@@ -81,14 +89,16 @@
 
        /**
         * @dataProvider WBLinkHeaderData
+        *
+        * @param string $titleText Text to use for the title.
+        * @param string $urlText Text to identify a title in a URL.
         */
        public  function  testCreateWBLinkHeader( $titleText, $urlText) {
                if ( defined( 'WB_VERSION' ) ) {
                        global $wgScript, $wgServer, $wgPubSubHubbubHubURL;
-
-                       $ns = \Wikibase\NamespaceUtils::getEntityNamespace( 
'wikibase-item' );
-                       $title = \Title::newFromText( $titleText, $ns );
-                       $article = new \Article( $title );
+                       $ns = NamespaceUtils::getEntityNamespace( 
'wikibase-item' );
+                       $title = Title::newFromText( $titleText, $ns );
+                       $article = new Article( $title );
 
                        $titleURL = $wgServer . $wgScript . 
"/Special:EntityData/" . $urlText . ".json";
                        $linkHeader = "Link: <" . $wgPubSubHubbubHubURL . ">; 
rel=\"hub\", <" . $titleURL . ">; rel=\"self\"";
@@ -101,8 +111,8 @@
        }
 
        public function testInsertLinkHeader() {
-               $title = \Title::newFromText( "TestTitle" );
-               $article = new \Article( $title );
+               $title = Title::newFromText( "TestTitle" );
+               $article = new Article( $title );
 
                PubSubHubbub::insertLinkHeader( $article );
 
@@ -113,28 +123,39 @@
                $this->assertEquals( $sExpectedLinkHeader, $sActualLinkHeader );
        }
 
+
+       /**
+        * The provider of data for testOnPageContentSaveComplete.
+        *
+        * @return array[array[Article, Revision|null, int]]
+        */
        public function contentSaveData() {
                $data = array();
 
-               $title = \Title::newFromText( "test" );
-               $article = new \Article( $title );
-               $baseRevId = false;
-               array_unshift( $data, array( $article, $baseRevId, 0 ) );
+               $title = Title::newFromText( "test" );
+               $article = new Article( $title );
 
-               $baseRevId = new \Status();
-               $baseRevId->value["revision"] = null;
-               array_unshift( $data, array( $article, $baseRevId, 0 ) );
+               $revision = null;
+               $data[] = array( $article, $revision, 0 );
 
-               $baseRevId = new \Status();
-               $baseRevId->value["revision"] = 1;
-               $data[] = array( $article, $baseRevId, 1 );
+               $revision = new Revision( array(
+                       'id' => 1,
+               ) );
+               $data[] = array( $article, $revision, 1 );
 
-               $baseRevId->value["revision"] = 100;
-               $data[] = array( $article, $baseRevId, 2 );
+               $revision = new Revision( array(
+                       'id' => 100,
+               ) );
+               $data[] = array( $article, $revision, 2 );
 
                return $data;
        }
 
+       /**
+        * The provider of data for testCreateLinkHeader.
+        *
+        * @return array[array[string, string]]
+        */
        public function  linkHeaderData() {
                return array(
                        array( 'test', 'Test' ),
@@ -144,6 +165,11 @@
                );
        }
 
+       /**
+        * The provider of data for testCreateWBLinkHeader.
+        *
+        * @return array[array[string, string]]
+        */
        public function  WBLinkHeaderData() {
                return array(
                        array( 'Item:Q2', 'Q2' ),
@@ -152,6 +178,11 @@
                );
        }
 
+       /**
+        * The provider of data for testIsConfigurationSetUp.
+        *
+        * @return array[array[null|string]]
+        */
        public function  configData() {
                return array(
                        array( null ),

-- 
To view, visit https://gerrit.wikimedia.org/r/124331
To unsubscribe, visit https://gerrit.wikimedia.org/r/settings

Gerrit-MessageType: merged
Gerrit-Change-Id: I53582bcb41fd82485f803422ccf3c1774c0af7a9
Gerrit-PatchSet: 5
Gerrit-Project: mediawiki/extensions/PubSubHubbub
Gerrit-Branch: master
Gerrit-Owner: Nik <[email protected]>
Gerrit-Reviewer: Alexander.lehmann 
<[email protected]>
Gerrit-Reviewer: Nik <[email protected]>
Gerrit-Reviewer: WikidataJenkins <[email protected]>

_______________________________________________
MediaWiki-commits mailing list
[email protected]
https://lists.wikimedia.org/mailman/listinfo/mediawiki-commits

Reply via email to