From 31f667ccf78f69f2c663a0a8c931e862182b6f2e Mon Sep 17 00:00:00 2001 From: "James D. Forrester" Date: Wed, 28 Mar 2018 12:47:04 -0700 Subject: [PATCH] doc: Document all public and protected PHP functions Also move the maintenane script to a name that makes MediaWiki.Files.ClassMatchesFilename.NotMatch not error, and use the more restrictive licence tag usage for MediaWiki.Commenting.LicenseComment.InvalidLicenseTag. Change-Id: Ifa5518cd590ae83c6fd76f1dbb5a2ce40de4b119 --- .phpcs.xml | 4 - VisualEditor.i18n.alias.php | 2 + VisualEditor.php | 2 +- includes/ApiVisualEditor.php | 62 +++++++++++- includes/ApiVisualEditorEdit.php | 97 ++++++++++++++++++- includes/SpecialCollabPad.php | 21 ++++ includes/VisualEditorDataModule.php | 15 ++- ...alEditorDesktopArticleTargetInitModule.php | 5 +- includes/VisualEditorHooks.php | 37 ++++++- ...ef.php => AutodisableVisualEditorPref.php} | 12 ++- 10 files changed, 244 insertions(+), 13 deletions(-) rename maintenance/{autodisablePref.php => AutodisableVisualEditorPref.php} (91%) diff --git a/.phpcs.xml b/.phpcs.xml index 1b9ca2baf0..cf6e0a8c1a 100644 --- a/.phpcs.xml +++ b/.phpcs.xml @@ -1,10 +1,6 @@ - - - - . diff --git a/VisualEditor.i18n.alias.php b/VisualEditor.i18n.alias.php index 9358273cf0..d1f097afc4 100644 --- a/VisualEditor.i18n.alias.php +++ b/VisualEditor.i18n.alias.php @@ -4,6 +4,8 @@ * * @file * @ingroup Extensions + * @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt + * @license MIT */ $specialPageAliases = []; diff --git a/VisualEditor.php b/VisualEditor.php index c35cfe8208..25de366294 100644 --- a/VisualEditor.php +++ b/VisualEditor.php @@ -9,7 +9,7 @@ * @file * @ingroup Extensions * @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt - * @license The MIT License (MIT); see LICENSE.txt + * @license MIT */ if ( function_exists( 'wfLoadExtension' ) ) { diff --git a/includes/ApiVisualEditor.php b/includes/ApiVisualEditor.php index 5e846b1d64..e36d57a3ef 100644 --- a/includes/ApiVisualEditor.php +++ b/includes/ApiVisualEditor.php @@ -5,7 +5,7 @@ * @file * @ingroup Extensions * @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt - * @license The MIT License (MIT); see LICENSE.txt + * @license MIT */ use MediaWiki\MediaWikiServices; @@ -21,6 +21,9 @@ class ApiVisualEditor extends ApiBase { */ protected $serviceClient; + /** + * @inheritDoc + */ public function __construct( ApiMain $main, $name, Config $config ) { parent::__construct( $main, $name ); $this->veConfig = $config; @@ -73,6 +76,15 @@ class ApiVisualEditor extends ApiBase { return new $class( $params ); } + /** + * Accessor function for all RESTbase requests + * + * @param string $method The HTTP method, either 'GET' or 'POST' + * @param string $path The RESTbase api path + * @param Array $params Request parameters + * @param Array $reqheaders Request headers + * @return string Body of the RESTbase server's response + */ protected function requestRestbase( $method, $path, $params, $reqheaders = [] ) { global $wgVersion; $request = [ @@ -117,6 +129,13 @@ class ApiVisualEditor extends ApiBase { return $response['body']; } + /** + * Run wikitext through the parser's Pre-Save-Transform + * + * @param string $title The title of the page to use as the parsing context + * @param string $wikitext The wikitext to transform + * @return string The transformed wikitext + */ protected function pstWikitext( $title, $wikitext ) { return ContentHandler::makeContent( $wikitext, $title, CONTENT_MODEL_WIKITEXT ) ->preSaveTransform( @@ -127,6 +146,14 @@ class ApiVisualEditor extends ApiBase { ->serialize( 'text/x-wiki' ); } + /** + * Provide the RESTbase-parsed HTML of a given fragment of wikitext + * + * @param string $title The title of the page to use as the parsing context + * @param string $wikitext The wikitext fragment to parse + * @param bool $bodyOnly Whether to provide only the contents of the `` tag + * @return string The parsed content HTML + */ protected function parseWikitextFragment( $title, $wikitext, $bodyOnly ) { return $this->requestRestbase( 'POST', @@ -138,6 +165,15 @@ class ApiVisualEditor extends ApiBase { ); } + /** + * Provide the preload content for a page being created from another page + * + * @param string $preload The title of the page to use as the preload content + * @param string[] $params The preloadTransform parameters to pass in, if any + * @param string $contextTitle The contextual page title against which to parse the preload + * @param bool $parse Whether to parse the preload content + * @return string The parsed content + */ protected function getPreloadContent( $preload, $params, $contextTitle, $parse = false ) { $content = ''; $preloadTitle = Title::newFromText( $preload ); @@ -169,6 +205,12 @@ class ApiVisualEditor extends ApiBase { return $content; } + /** + * Provide the current language links for a given page title + * + * @param string $title The page title for which to get the current language links + * @return string[] The language links + */ protected function getLangLinks( $title ) { $apiParams = [ 'action' => 'query', @@ -204,6 +246,9 @@ class ApiVisualEditor extends ApiBase { return $langlinks; } + /** + * @inheritDoc + */ public function execute() { $this->serviceClient->mount( '/restbase/', $this->getVRSObject() ); @@ -703,6 +748,9 @@ class ApiVisualEditor extends ApiBase { ); } + /** + * @inheritDoc + */ public function getAllowedParams() { return [ 'page' => [ @@ -735,18 +783,30 @@ class ApiVisualEditor extends ApiBase { ]; } + /** + * @inheritDoc + */ public function needsToken() { return false; } + /** + * @inheritDoc + */ public function mustBePosted() { return false; } + /** + * @inheritDoc + */ public function isInternal() { return true; } + /** + * @inheritDoc + */ public function isWriteMode() { return false; } diff --git a/includes/ApiVisualEditorEdit.php b/includes/ApiVisualEditorEdit.php index 1eabe45139..d11d3bfe8e 100644 --- a/includes/ApiVisualEditorEdit.php +++ b/includes/ApiVisualEditorEdit.php @@ -5,7 +5,7 @@ * @file * @ingroup Extensions * @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt - * @license The MIT License (MIT); see LICENSE.txt + * @license MIT */ use \MediaWiki\Logger\LoggerFactory; @@ -13,10 +13,21 @@ use MediaWiki\MediaWikiServices; class ApiVisualEditorEdit extends ApiVisualEditor { + /** + * @inheritDoc + */ public function __construct( ApiMain $main, $name, Config $config ) { parent::__construct( $main, $name, $config ); } + /** + * Attempt to save a given page's wikitext to MediaWiki's storage layer via its API + * + * @param string $title The title of the page to write + * @param string $wikitext The wikitext to write + * @param array $params The edit parameters + * @return Status The result of the save attempt + */ protected function saveWikitext( $title, $wikitext, $params ) { $apiParams = [ 'action' => 'edit', @@ -60,6 +71,12 @@ class ApiVisualEditorEdit extends ApiVisualEditor { return $api->getResult()->getResultData(); } + /** + * Load into an array the output of MediaWiki's parser for a given revision + * + * @param int $newRevId The revision to load + * @return array The parsed of the save attempt + */ protected function parseWikitext( $newRevId ) { $apiParams = [ 'action' => 'parse', @@ -118,6 +135,12 @@ class ApiVisualEditorEdit extends ApiVisualEditor { ]; } + /** + * Attempt to compress a given text string via deflate + * + * @param string $content The string to compress + * @return string The compressed string, or the original if deflating failed + */ public static function tryDeflate( $content ) { if ( substr( $content, 0, 11 ) === 'rawdeflate,' ) { $deflated = base64_decode( substr( $content, 11 ) ); @@ -137,6 +160,14 @@ class ApiVisualEditorEdit extends ApiVisualEditor { return $content; } + /** + * Create and load the parsed wikitext of an edit, or from the serialisation cache if available. + * + * @param string $title The title of the page + * @param array $params The edit parameters + * @param array $parserParams The parser parameters + * @return string The wikitext of the edit + */ protected function getWikitext( $title, $params, $parserParams ) { if ( $params['cachekey'] !== null ) { $wikitext = $this->trySerializationCache( $params['cachekey'] ); @@ -149,6 +180,14 @@ class ApiVisualEditorEdit extends ApiVisualEditor { return $wikitext; } + /** + * Create and load the parsed wikitext of an edit, ignoring the serialisation cache. + * + * @param string $title The title of the page + * @param array $params The edit parameters + * @param array $parserParams The parser parameters + * @return string The wikitext of the edit + */ protected function getWikitextNoCache( $title, $params, $parserParams ) { $this->requireOnlyOneParameter( $params, 'html' ); $wikitext = $this->postHTML( @@ -160,6 +199,13 @@ class ApiVisualEditorEdit extends ApiVisualEditor { return $wikitext; } + /** + * Load the parsed wikitext of an edit into the serialisation cache. + * + * @param string $title The title of the page + * @param string $wikitext The wikitext of the edit + * @return string The key of the wikitext in the serialisation cache + */ protected function storeInSerializationCache( $title, $wikitext ) { global $wgMemc; @@ -189,12 +235,28 @@ class ApiVisualEditorEdit extends ApiVisualEditor { return $hash; } + /** + * Load some parsed wikitext of an edit from the serialisation cache. + * + * @param string $hash The key of the wikitext in the serialisation cache + * @return string|null The wikitext + */ protected function trySerializationCache( $hash ) { global $wgMemc; $key = wfMemcKey( 'visualeditor', 'serialization', $hash ); return $wgMemc->get( $key ); } + /** + * Transform HTML to wikitext via Parsoid through RESTbase. + * + * @param string $path The RESTbase path of the transform endpoint + * @param string $title The title of the page + * @param array $data An array of the HTML and the 'scrub_wikitext' option + * @param array $parserParams Parsoid parser paramters to pass in + * @param string $etag The ETag to set in the HTTP request header + * @return string Body of the RESTbase server's response + */ protected function postData( $path, $title, $data, $parserParams, $etag ) { $path .= urlencode( $title->getPrefixedDBkey() ); if ( isset( $parserParams['oldid'] ) && $parserParams['oldid'] ) { @@ -206,6 +268,15 @@ class ApiVisualEditorEdit extends ApiVisualEditor { ); } + /** + * Transform HTML to wikitext via Parsoid through RESTbase. Wrapper for ::postData(). + * + * @param string $title The title of the page + * @param string $html The HTML of the page to be transformed + * @param array $parserParams Parsoid parser paramters to pass in + * @param string $etag The ETag to set in the HTTP request header + * @return string Body of the RESTbase server's response + */ protected function postHTML( $title, $html, $parserParams, $etag ) { return $this->postData( 'transform/html/to/wikitext/', $title, @@ -213,6 +284,15 @@ class ApiVisualEditorEdit extends ApiVisualEditor { ); } + /** + * Calculate the different between the wikitext of an edit and an existing revision. + * + * @param string $title The title of the page + * @param int $fromId The existing revision of the page to compare with + * @param string $wikitext The wikitext to compare against + * @param int|null $section Whether the wikitext refers to a given section or the whole page + * @return array The comparison, or `[ 'result' => 'nochanges' ]` if there are none + */ protected function diffWikitext( $title, $fromId, $wikitext, $section = null ) { $apiParams = [ 'action' => 'compare', @@ -259,6 +339,9 @@ class ApiVisualEditorEdit extends ApiVisualEditor { } } + /** + * @inheritDoc + */ public function execute() { $this->serviceClient->mount( '/restbase/', $this->getVRSObject() ); @@ -399,6 +482,9 @@ class ApiVisualEditorEdit extends ApiVisualEditor { $this->getResult()->addValue( null, $this->getModuleName(), $result ); } + /** + * @inheritDoc + */ public function getAllowedParams() { return [ 'paction' => [ @@ -433,14 +519,23 @@ class ApiVisualEditorEdit extends ApiVisualEditor { ]; } + /** + * @inheritDoc + */ public function needsToken() { return 'csrf'; } + /** + * @inheritDoc + */ public function mustBePosted() { return true; } + /** + * @inheritDoc + */ public function isWriteMode() { return true; } diff --git a/includes/SpecialCollabPad.php b/includes/SpecialCollabPad.php index 43c0868f8e..b4cda318a9 100644 --- a/includes/SpecialCollabPad.php +++ b/includes/SpecialCollabPad.php @@ -1,4 +1,13 @@ setHeaders(); $this->checkPermissions(); diff --git a/includes/VisualEditorDataModule.php b/includes/VisualEditorDataModule.php index 706dcc1113..e4b799bc9d 100644 --- a/includes/VisualEditorDataModule.php +++ b/includes/VisualEditorDataModule.php @@ -5,7 +5,7 @@ * @file * @ingroup Extensions * @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt - * @license The MIT License (MIT); see LICENSE.txt + * @license MIT */ class VisualEditorDataModule extends ResourceLoaderModule { @@ -43,6 +43,11 @@ class VisualEditorDataModule extends ResourceLoaderModule { ) . ');'; } + /** + * @param ResourceLoaderContext $context Object containing information about the state of this + * specific loader request. + * @return string[] Messages in various states of parsing + */ protected function getMessageInfo( ResourceLoaderContext $context ) { $editSubmitButtonLabelPublish = $context->getResourceLoader()->getConfig() ->get( 'EditSubmitButtonLabelPublish' ); @@ -85,10 +90,18 @@ class VisualEditorDataModule extends ResourceLoaderModule { ]; } + /** + * @inheritDoc + * + * Always true. + */ public function enableModuleContentVersion() { return true; } + /** + * @inheritDoc + */ public function getDependencies( ResourceLoaderContext $context = null ) { return [ 'ext.visualEditor.base', diff --git a/includes/VisualEditorDesktopArticleTargetInitModule.php b/includes/VisualEditorDesktopArticleTargetInitModule.php index bd687c637e..9be9685313 100644 --- a/includes/VisualEditorDesktopArticleTargetInitModule.php +++ b/includes/VisualEditorDesktopArticleTargetInitModule.php @@ -7,11 +7,14 @@ * @file * @ingroup Extensions * @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt - * @license The MIT License (MIT); see LICENSE.txt + * @license MIT */ class VisualEditorDesktopArticleTargetInitModule extends ResourceLoaderFileModule { + /** + * @inheritDoc + */ public function __construct( $options = [], $localBasePath = null, diff --git a/includes/VisualEditorHooks.php b/includes/VisualEditorHooks.php index 5fe433f1cd..8a4ac7fcd7 100644 --- a/includes/VisualEditorHooks.php +++ b/includes/VisualEditorHooks.php @@ -5,7 +5,7 @@ * @file * @ingroup Extensions * @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt - * @license The MIT License (MIT); see LICENSE.txt + * @license MIT */ use MediaWiki\MediaWikiServices; @@ -36,6 +36,13 @@ class VisualEditorHooks { } } + /** + * Factory to return the relevant API class + * + * @param ApiMain $main The ApiMain instance + * @param string $name The api request name + * @return ApiVisualEditor|ApiVisualEditorEdit API class + */ public static function getVisualEditorApiFactory( $main, $name ) { $config = ConfigFactory::getDefaultInstance()->makeConfig( 'visualeditor' ); $class = $name === 'visualeditor' ? 'ApiVisualEditor' : 'ApiVisualEditorEdit'; @@ -75,6 +82,14 @@ class VisualEditorHooks { return true; } + /** + * Handler for the DiffViewHeader hook, to add visual diffs code as configured + * + * @param DifferenceEngine $diff The difference engine + * @param Revision $oldRev The old revision + * @param Revision $newRev The new revision + * @return bool Always true + */ public static function onDiffViewHeader( DifferenceEngine $diff, Revision $oldRev = null, @@ -631,6 +646,13 @@ class VisualEditorHooks { } } + /** + * Handler for the GetPreferences hook, to add and hide user preferences as configured + * + * @param User $user The user object + * @param array &$preferences Their preferences object + * @return bool Always true + */ public static function onGetPreferences( User $user, array &$preferences ) { global $wgLang; $veConfig = ConfigFactory::getDefaultInstance()->makeConfig( 'visualeditor' ); @@ -717,6 +739,12 @@ class VisualEditorHooks { return true; } + /** + * Handler for the GetBetaPreferences hook, to add and hide user beta preferences as configured + * + * @param User $user The user object + * @param array &$preferences Their preferences object + */ public static function onGetBetaPreferences( User $user, array &$preferences ) { $coreConfig = RequestContext::getMain()->getConfig(); $iconpath = $coreConfig->get( 'ExtensionAssetsPath' ) . "/VisualEditor/images"; @@ -971,6 +999,13 @@ class VisualEditorHooks { return true; } + /** + * Handler for the ResourceLoaderTestModules hook given we can't do this statically yet. + * + * @param array &$testModules The ResourceLoader test modules array + * @param ResourceLoader &$resourceLoader The ResourceLoader controller + * @return bool Always true + */ public static function onResourceLoaderTestModules( array &$testModules, ResourceLoader &$resourceLoader diff --git a/maintenance/autodisablePref.php b/maintenance/AutodisableVisualEditorPref.php similarity index 91% rename from maintenance/autodisablePref.php rename to maintenance/AutodisableVisualEditorPref.php index d33fd903bd..c4617f5c66 100644 --- a/maintenance/autodisablePref.php +++ b/maintenance/AutodisableVisualEditorPref.php @@ -3,7 +3,7 @@ * Sets the VisualEditor autodisable preference on appropriate users. * * @copyright 2011-2018 VisualEditor Team and others; see AUTHORS.txt - * @license The MIT License (MIT); see LICENSE.txt + * @license MIT * @author Alex Monk * @file * @ingroup Extensions @@ -16,7 +16,10 @@ $maintenancePath = getenv( 'MW_INSTALL_PATH' ) !== false require_once $maintenancePath; -class VEAutodisablePref extends Maintenance { +class AutodisableVisualEditorPref extends Maintenance { + /** + * @inheritDoc + */ public function __construct() { parent::__construct(); $this->requireExtension( 'VisualEditor' ); @@ -24,6 +27,9 @@ class VEAutodisablePref extends Maintenance { $this->setBatchSize( 500 ); } + /** + * @inheritDoc + */ public function execute() { $dbr = wfGetDB( DB_REPLICA ); @@ -64,5 +70,5 @@ class VEAutodisablePref extends Maintenance { } } -$maintClass = "VEAutodisablePref"; +$maintClass = "AutodisableVisualEditorPref"; require_once RUN_MAINTENANCE_IF_MAIN;