Mark exceptions as @newable

Exceptions classes are nearly always value objects, and should in most
cases by newable.

Bug: T247862
Change-Id: I4faa8ec6ea8bc44086cfc8075b32d10eea61e9df

includes/Rest/HttpException.php

@@ -6,12 +6,21 @@ namespace MediaWiki\Rest;
  * This is the base exception class for non-fatal exceptions thrown from REST
  * handlers. The exception is not logged, it is merely converted to an
  * error response.
+ *
+ * @newable
  */
 class HttpException extends \Exception {
 
 	/** @var array|null */
 	private $errorData = null;
 
+	/**
+	 * @stable for calling
+	 *
+	 * @param string $message
+	 * @param int $code
+	 * @param null $errorData
+	 */
 	public function __construct( $message, $code = 500, $errorData = null ) {
 		parent::__construct( $message, $code );
 		$this->errorData = $errorData;

includes/Rest/LocalizedHttpException.php

@@ -4,9 +4,19 @@ namespace MediaWiki\Rest;
 
 use Wikimedia\Message\MessageValue;
 
+/**
+ * @newable
+ */
 class LocalizedHttpException extends HttpException {
 	private $messageValue;
 
+	/**
+	 * @stable for calling
+	 *
+	 * @param MessageValue $messageValue
+	 * @param int $code
+	 * @param null $errorData
+	 */
 	public function __construct( MessageValue $messageValue, $code = 500, $errorData = null ) {
 		parent::__construct(
 			'Localized exception with key ' . $messageValue->getKey(), $code, $errorData

includes/Rest/PathTemplateMatcher/PathConflict.php

@@ -4,12 +4,22 @@ namespace MediaWiki\Rest\PathTemplateMatcher;
 
 use Exception;
 
+/**
+ * @newable
+ */
 class PathConflict extends Exception {
 	public $newTemplate;
 	public $newUserData;
 	public $existingTemplate;
 	public $existingUserData;
 
+	/**
+	 * @stable for calling
+	 *
+	 * @param string $template
+	 * @param mixed $userData
+	 * @param array $existingNode
+	 */
 	public function __construct( $template, $userData, $existingNode ) {
 		$this->newTemplate = $template;
 		$this->newUserData = $userData;

includes/Revision/IncompleteRevisionException.php

@@ -25,6 +25,7 @@ namespace MediaWiki\Revision;
 /**
  * Exception throw when trying to access undefined fields on an incomplete RevisionRecord.
  *
+ * @newable
  * @since 1.31
  * @since 1.32 Renamed from MediaWiki\Storage\IncompleteRevisionException
  */

includes/Revision/RevisionAccessException.php

@@ -27,6 +27,7 @@ use RuntimeException;
 /**
  * Exception representing a failure to look up a revision.
  *
+ * @newable
  * @since 1.31
  * @since 1.32 Renamed from MediaWiki\Storage\RevisionAccessException
  */

includes/Revision/SuppressedDataException.php

@@ -26,6 +26,7 @@ namespace MediaWiki\Revision;
  * Exception raised in response to an audience check when attempting to
  * access suppressed information without permission.
  *
+ * @newable
  * @since 1.31
  * @since 1.32 Renamed from MediaWiki\Storage\SuppressedDataException
  */

includes/Storage/BlobAccessException.php

@@ -27,6 +27,7 @@ use RuntimeException;
 /**
  * Exception representing a failure to access a data blob.
  *
+ * @newable
  * @since 1.31
  */
 class BlobAccessException extends RuntimeException {

includes/Storage/NameTableAccessException.php

@@ -27,6 +27,7 @@ use RuntimeException;
 /**
  * Exception representing a failure to look up a row from a name table.
  *
+ * @newable
  * @since 1.31
  */
 class NameTableAccessException extends RuntimeException {

includes/Storage/PageUpdateException.php

@@ -27,6 +27,7 @@ use RuntimeException;
 /**
  * Exception representing a failure to update a page entry.
  *
+ * @newable
  * @since 1.32
  */
 class PageUpdateException extends RuntimeException {

includes/api/ApiUsageException.php

@@ -23,6 +23,7 @@
  *
  * If possible, use ApiBase::dieWithError() instead of throwing this directly.
  *
+ * @newable
  * @ingroup API
  */
 class ApiUsageException extends MWException implements ILocalizedException {
@@ -31,6 +32,8 @@ class ApiUsageException extends MWException implements ILocalizedException {
 	protected $status;
 
 	/**
+	 *
+	 * @stable for calling
 	 * @param ApiBase|null $module API module responsible for the error, if known
 	 * @param StatusValue $status Status holding errors
 	 * @param int $httpCode HTTP error code to use

includes/config/ConfigException.php

@@ -23,6 +23,7 @@
 /**
  * Exceptions for config failures
  *
+ * @newable
  * @since 1.23
  */
 class ConfigException extends LogicException {

includes/config/EtcdConfigParseError.php

@@ -1,4 +1,7 @@
 <?php
 
+/**
+ * @newable
+ */
 class EtcdConfigParseError extends Exception {
 }

includes/diff/ComplexityException.php

@@ -23,7 +23,14 @@ namespace MediaWiki\Diff;
 
 use Exception;
 
+/**
+ * @newable
+ */
 class ComplexityException extends Exception {
+
+	/**
+	 * @stable for calling
+	 */
 	public function __construct() {
 		parent::__construct( 'Diff is too complex to generate' );
 	}

includes/exception/CannotCreateActorException.php

@@ -24,6 +24,7 @@
 
 /**
  * Exception thrown when an actor can't be created.
+ * @newable
  */
 class CannotCreateActorException extends RuntimeException {
 }

includes/exception/FatalError.php

@@ -29,6 +29,7 @@
  * It is intended for early installation and configuration problems where
  * the exception is all the site administrator needs to know.
  *
+ * @newable
  * @since 1.7
  * @ingroup Exception
  */

includes/exception/HttpError.php

@@ -24,6 +24,7 @@ use MediaWiki\Logger\LoggerFactory;
  * Show an error that looks like an HTTP server error.
  * Replacement for wfHttpError().
  *
+ * @newable
  * @since 1.19
  * @ingroup Exception
  */
@@ -31,6 +32,7 @@ class HttpError extends MWException {
 	private $httpCode, $header, $content;
 
 	/**
+	 * @stable for calling
 	 * @param int $httpCode HTTP status code to send to the client
 	 * @param string|Message $content Content of the message
 	 * @param string|Message|null $header Content of the header (\<title\> and \<h1\>)

includes/exception/LocalizedException.php

@@ -21,6 +21,7 @@
 /**
  * Basic localized exception.
  *
+ * @newable
  * @since 1.29
  * @ingroup Exception
  * @note Don't use this in a situation where MessageCache is not functional.
@@ -30,6 +31,7 @@ class LocalizedException extends Exception implements ILocalizedException {
 	protected $messageSpec;
 
 	/**
+	 * @stable for calling
 	 * @param string|array|MessageSpecifier $messageSpec See Message::newFromSpecifier
 	 * @param int $code
 	 * @param Throwable|null $previous The previous exception used for the exception

includes/exception/MWContentSerializationException.php

@@ -2,6 +2,7 @@
 /**
  * Exception representing a failure to serialize or unserialize a content object.
  *
+ * @newable
  * @ingroup Content
  */
 class MWContentSerializationException extends MWException {

includes/exception/MWUnknownContentModelException.php

@@ -4,6 +4,7 @@
  * can be triggered by user input, so a separate exception class is provided so
  * callers can substitute a context-specific, internationalised error message.
  *
+ * @newable
  * @ingroup Content
  * @since 1.27
  */
@@ -11,7 +12,10 @@ class MWUnknownContentModelException extends MWException {
 	/** @var string The name of the unknown content model */
 	private $modelId;
 
-	/** @param string $modelId */
+	/**
+	 * @stable for calling
+	 * @param string $modelId
+	 */
 	public function __construct( $modelId ) {
 		parent::__construct( "The content model '$modelId' is not registered on this wiki.\n" .
 			'See https://www.mediawiki.org/wiki/Content_handlers to find out which extensions ' .

includes/exception/ProcOpenError.php

@@ -22,7 +22,13 @@ namespace MediaWiki;
 
 use Exception;
 
+/**
+ * @newable
+ */
 class ProcOpenError extends Exception {
+	/**
+	 * @stable for calling
+	 */
 	public function __construct() {
 		parent::__construct( 'proc_open() returned error!' );
 	}

includes/exception/ShellDisabledError.php

@@ -23,9 +23,14 @@ namespace MediaWiki;
 use Exception;
 
 /**
+ * @newable
  * @since 1.30
  */
 class ShellDisabledError extends Exception {
+
+	/**
+	 * @stable for calling
+	 */
 	public function __construct() {
 		parent::__construct( 'Unable to run external programs, proc_open() is disabled' );
 	}

includes/externalstore/ExternalStoreException.php

@@ -1,5 +1,8 @@
 <?php
 
+/**
+ * @newable
+ */
 class ExternalStoreException extends MWException {
 
 }

includes/htmlform/HTMLFormFieldRequiredOptionsException.php

@@ -1,6 +1,16 @@
 <?php
 
+/**
+ * @newable
+ */
 class HTMLFormFieldRequiredOptionsException extends MWException {
+
+	/**
+	 * @stable for calling
+	 *
+	 * @param HTMLFormField $field
+	 * @param array $missing
+	 */
 	public function __construct( HTMLFormField $field, array $missing ) {
 		parent::__construct( sprintf( "Form type `%s` expected the following parameters to be set: %s",
 			get_class( $field ),

includes/jobqueue/exception/JobQueueError.php

@@ -22,6 +22,7 @@
  */
 
 /**
+ * @newable
  * @ingroup JobQueue
  * @since 1.22
  */

includes/libs/ParamValidator/ValidationException.php

@@ -9,6 +9,7 @@ use Wikimedia\Message\DataMessageValue;
 /**
  * Error reporting for ParamValidator
  *
+ * @newable
  * @since 1.34
  * @unstable
  */
@@ -27,6 +28,7 @@ class ValidationException extends UnexpectedValueException {
 	protected $settings;
 
 	/**
+	 * @stable for calling
 	 * @param DataMessageValue $failureMessage Failure message.
 	 * @param string $name Parameter name being validated
 	 * @param mixed $value Value of the parameter

includes/libs/filebackend/exception/FileBackendError.php

@@ -2,6 +2,7 @@
 /**
  * File backend exception for checked exceptions (e.g. I/O errors)
  *
+ * @newable
  * @ingroup FileBackend
  * @since 1.22
  */

includes/libs/rdbms/exception/DBError.php

@@ -25,6 +25,7 @@ use RuntimeException;
 
 /**
  * Database error base class
+ * @newable
  * @ingroup Database
  */
 class DBError extends RuntimeException {
@@ -33,6 +34,7 @@ class DBError extends RuntimeException {
 
 	/**
 	 * Construct a database error
+	 * @stable for calling
 	 * @param IDatabase|null $db Object which threw the error
 	 * @param string $error A simple error message to be used for debugging
 	 * @param \Throwable|null $prev Previous throwable

includes/media/MediaTransformError.php

@@ -24,12 +24,21 @@
 /**
  * Basic media transform error class
  *
+ * @newable
  * @ingroup Media
  */
 class MediaTransformError extends MediaTransformOutput {
 	/** @var Message */
 	private $msg;
 
+	/**
+	 * @stable for calling
+	 *
+	 * @param string $msg
+	 * @param int $width
+	 * @param int $height
+	 * @param mixed ...$args
+	 */
 	public function __construct( $msg, $width, $height, ...$args ) {
 		$this->msg = wfMessage( $msg )->params( $args );
 		$this->width = intval( $width );

includes/media/MediaTransformInvalidParametersException.php

@@ -21,6 +21,7 @@
 /**
  * MediaWiki exception thrown by some methods when the transform parameter array is invalid
  *
+ * @newable
  * @ingroup Exception
  */
 class MediaTransformInvalidParametersException extends MWException {

includes/password/PasswordError.php

@@ -23,6 +23,7 @@ declare( strict_types = 1 );
 /**
  * Show an error when any operation involving passwords fails to run.
  *
+ * @newable
  * @ingroup Exception
  */
 class PasswordError extends MWException {

includes/registration/ExtensionDependencyError.php

@@ -19,6 +19,7 @@
  */
 
 /**
+ * @newable
  * @since 1.31
  */
 class ExtensionDependencyError extends Exception {

includes/registration/ExtensionJsonValidationError.php

@@ -18,5 +18,9 @@
  *
  * @file
  */
+
+/**
+ * @newable
+ */
 class ExtensionJsonValidationError extends Exception {
 }

includes/resourceloader/dependencystore/DependencyStoreException.php

@@ -5,6 +5,7 @@ namespace Wikimedia\DependencyStore;
 use RuntimeException;
 
 /**
+ * @stable to type
  * @since 1.35
  */
 class DependencyStoreException extends RuntimeException {

includes/session/MetadataMergeException.php

@@ -16,6 +16,7 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @copyright © 2016 Wikimedia Foundation and contributors
  * @file
  * @ingroup Session
  */
@@ -29,7 +30,7 @@ use UnexpectedValueException;
  * Subclass of UnexpectedValueException that can be annotated with additional
  * data for debug logging.
  *
- * @copyright © 2016 Wikimedia Foundation and contributors
+ * @newable
  * @since 1.27
  */
 class MetadataMergeException extends UnexpectedValueException {

includes/skins/SkinException.php

@@ -23,6 +23,7 @@
 /**
  * Exceptions for skin-related failures
  *
+ * @newable
  * @since 1.24
  */
 class SkinException extends MWException {

includes/sparql/SparqlException.php

@@ -15,6 +15,7 @@
  * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  * http://www.gnu.org/copyleft/gpl.html
  *
+ * @author Stas Malyshev
  * @file
  */
 
@@ -24,7 +25,7 @@ use Exception;
 
 /**
  * Exception for SPARQLClient
- * @author Stas Malyshev
+ * @newable
  */
 class SparqlException extends Exception {
 }

includes/specials/exception/SpecialUploadStashTooLargeException.php

@@ -21,6 +21,7 @@
  */
 
 /**
+ * @newable
  * @ingroup SpecialPage
  * @ingroup Upload
  */

includes/title/MalformedTitleException.php

@@ -20,6 +20,7 @@
 
 /**
  * MalformedTitleException is thrown when a TitleParser is unable to parse a title string.
+ * @newable
  * @since 1.23
  */
 class MalformedTitleException extends Exception implements ILocalizedException {
@@ -28,6 +29,7 @@ class MalformedTitleException extends Exception implements ILocalizedException {
 	private $errorMessageParameters = [];
 
 	/**
+	 * @stable for calling
 	 * @param string $errorMessage Localisation message describing the error (since MW 1.26)
 	 * @param string|null $titleText The invalid title text (since MW 1.26)
 	 * @param string[] $errorMessageParameters Additional parameters for the error message.

includes/upload/exception/UploadChunkFileException.php

@@ -21,5 +21,8 @@
  * @ingroup Upload
  */
 
+/**
+ * @newable
+ */
 class UploadChunkFileException extends MWException {
 }

includes/upload/exception/UploadChunkVerificationException.php

@@ -21,6 +21,9 @@
  * @ingroup Upload
  */
 
+/**
+ * @newable
+ */
 class UploadChunkVerificationException extends MWException {
 	public $msg;
 

includes/upload/exception/UploadChunkZeroLengthFileException.php

@@ -21,5 +21,8 @@
  * @ingroup Upload
  */
 
+/**
+ * @newable
+ */
 class UploadChunkZeroLengthFileException extends MWException {
 }

includes/upload/exception/UploadStashBadPathException.php

@@ -21,6 +21,7 @@
  */
 
 /**
+ * @newable
  * @ingroup Upload
  */
 class UploadStashBadPathException extends UploadStashException {

includes/upload/exception/UploadStashException.php

@@ -21,6 +21,7 @@
  */
 
 /**
+ * @newable
  * @ingroup Upload
  */
 class UploadStashException extends MWException implements ILocalizedException {

includes/upload/exception/UploadStashFileException.php

@@ -21,6 +21,7 @@
  */
 
 /**
+ * @newable
  * @ingroup Upload
  */
 class UploadStashFileException extends UploadStashException {

includes/upload/exception/UploadStashFileNotFoundException.php

@@ -21,6 +21,7 @@
  */
 
 /**
+ * @newable
  * @ingroup Upload
  */
 class UploadStashFileNotFoundException extends UploadStashException {

includes/upload/exception/UploadStashNoSuchKeyException.php

@@ -21,6 +21,7 @@
  */
 
 /**
+ * @newable
  * @ingroup Upload
  */
 class UploadStashNoSuchKeyException extends UploadStashException {

includes/upload/exception/UploadStashNotLoggedInException.php

@@ -21,6 +21,7 @@
  */
 
 /**
+ * @newable
  * @ingroup Upload
  */
 class UploadStashNotLoggedInException extends UploadStashException {

includes/upload/exception/UploadStashWrongOwnerException.php

@@ -21,6 +21,7 @@
  */
 
 /**
+ * @newable
  * @ingroup Upload
  */
 class UploadStashWrongOwnerException extends UploadStashException {

includes/upload/exception/UploadStashZeroLengthFileException.php

@@ -21,6 +21,7 @@
  */
 
 /**
+ * @newable
  * @ingroup Upload
  */
 class UploadStashZeroLengthFileException extends UploadStashException {

includes/utils/ZipDirectoryReaderError.php

@@ -20,10 +20,16 @@
 
 /**
  * Internal exception class. Will be caught by private code.
+ * @newable
  */
 class ZipDirectoryReaderError extends Exception {
 	protected $errorCode;
 
+	/**
+	 * @stable for calling
+	 *
+	 * @param mixed $code
+	 */
 	public function __construct( $code ) {
 		$this->errorCode = $code;
 		parent::__construct( "ZipDirectoryReader error: $code" );