Clarify some HTML / plain text strings

Mistaking getDimensionsString() for another HTML-returning method has
now caused two separate security vulnerabilities, so let’s try to make
it clearer that it returns plain text that a caller might have to escape
themselves.

Bug: T297543
Bug: T389369
Change-Id: I567f78c60e38ce0fa9d9ad6312860baec559c00f

2 files changed, 8 insertions, 8 deletions

diff --git a/includes/filerepo/file/File.php b/includes/filerepo/file/File.php
index 30844f5c2059..ed7b5d84b88b 100644
--- a/includes/filerepo/file/File.php
+++ b/includes/filerepo/file/File.php
@@ -2465,7 +2465,7 @@ abstract class File implements MediaHandlerState {
 	}
 
 	/**
-	 * @return string
+	 * @return string HTML
 	 */
 	public function getLongDesc() {
 		$handler = $this->getHandler();
@@ -2477,7 +2477,7 @@ abstract class File implements MediaHandlerState {
 	}
 
 	/**
-	 * @return string
+	 * @return string HTML
 	 */
 	public function getShortDesc() {
 		$handler = $this->getHandler();
@@ -2489,7 +2489,7 @@ abstract class File implements MediaHandlerState {
 	}
 
 	/**
-	 * @return string
+	 * @return string plain text
 	 */
 	public function getDimensionsString() {
 		$handler = $this->getHandler();
diff --git a/includes/media/MediaHandler.php b/includes/media/MediaHandler.php
index c5ec3c403c8b..cc7a092e3341 100644
--- a/includes/media/MediaHandler.php
+++ b/includes/media/MediaHandler.php
@@ -818,7 +818,7 @@ abstract class MediaHandler {
 	 * @stable to override
 	 *
 	 * @param File $file
-	 * @return string
+	 * @return string HTML
 	 */
 	public function getShortDesc( $file ) {
 		return self::getGeneralShortDesc( $file );
@@ -830,7 +830,7 @@ abstract class MediaHandler {
 	 * @stable to override
 	 *
 	 * @param File $file
-	 * @return string
+	 * @return string HTML
 	 */
 	public function getLongDesc( $file ) {
 		return self::getGeneralLongDesc( $file );
@@ -840,7 +840,7 @@ abstract class MediaHandler {
 	 * Used instead of getShortDesc if there is no handler registered for file.
 	 *
 	 * @param File $file
-	 * @return string
+	 * @return string HTML
 	 */
 	public static function getGeneralShortDesc( $file ) {
 		global $wgLang;
@@ -852,7 +852,7 @@ abstract class MediaHandler {
 	 * Used instead of getLongDesc if there is no handler registered for file.
 	 *
 	 * @param File $file
-	 * @return string
+	 * @return string HTML
 	 */
 	public static function getGeneralLongDesc( $file ) {
 		return wfMessage( 'file-info' )->sizeParams( $file->getSize() )
@@ -882,7 +882,7 @@ abstract class MediaHandler {
 	 * @stable to override
 	 *
 	 * @param File $file
-	 * @return string Dimensions
+	 * @return string Dimensions (plain text)
 	 */
 	public function getDimensionsString( $file ) {
 		return '';