From 8360322b04255cd85b5cc57a048fc5f725d82879 Mon Sep 17 00:00:00 2001
From: Timo Tijhof <krinkle@fastmail.com>
Date: Wed, 13 Mar 2024 12:39:49 -0700
Subject: mime: Improve docs, add ingroup tags to class doc blocks

* Remove redundant file-level description and ensure the class desc
  and ingroup tag are on the class block instead.
  Ref https://gerrit.wikimedia.org/r/q/owner:Krinkle+message:ingroup

  Also remove `@group` from `@file` block in MediaHandler.php,
  which caused an unhelpful duplicate to be shown in the navigation
  on doc.wikimedia.org.

* Create a new "Mime" doc group, and tag all wikimedia/mime classes
  with it. Organize it as a subgroup of "Media", matching the way
  its tests and other classes relating to handling of media uploads.

* Remove dependency on wikimedia/at-ease per T253461.

Change-Id: If7629db2f33ba8059c5d58d2992488f8f49be373
---
 includes/libs/mime/MSCompoundFileReader.php | 13 +++++--------
 includes/libs/mime/MimeAnalyzer.php         | 11 ++++++++---
 includes/libs/mime/MimeMap.php              |  4 ++--
 includes/libs/mime/MimeMapMinimal.php       |  6 +++---
 includes/libs/mime/XmlTypeCheck.php         | 19 ++++++++++++-------
 includes/libs/mime/defines.php              |  1 +
 6 files changed, 31 insertions(+), 23 deletions(-)

(limited to 'includes/libs/mime')

diff --git a/includes/libs/mime/MSCompoundFileReader.php b/includes/libs/mime/MSCompoundFileReader.php
index 121994a2152a..6bcc61290400 100644
--- a/includes/libs/mime/MSCompoundFileReader.php
+++ b/includes/libs/mime/MSCompoundFileReader.php
@@ -14,8 +14,6 @@
  * specific language governing permissions and limitations under the License.
  */
 
-use Wikimedia\AtEase\AtEase;
-
 /**
  * Read the directory of a Microsoft Compound File Binary file, a.k.a. an OLE
  * file, and detect the MIME type.
@@ -30,6 +28,7 @@ use Wikimedia\AtEase\AtEase;
  *    File Format https://www.openoffice.org/sc/compdocfileformat.pdf
  *
  * @since 1.33
+ * @ingroup Mime
  */
 class MSCompoundFileReader {
 	private $file;
@@ -218,9 +217,8 @@ class MSCompoundFileReader {
 
 	private function readOffset( $offset, $length ) {
 		$this->fseek( $offset );
-		AtEase::suppressWarnings();
-		$block = fread( $this->file, $length );
-		AtEase::restoreWarnings();
+		// phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged
+		$block = @fread( $this->file, $length );
 		if ( $block === false ) {
 			$this->error( 'error reading from file', self::ERROR_READ );
 		}
@@ -245,9 +243,8 @@ class MSCompoundFileReader {
 	}
 
 	private function fseek( $offset ) {
-		AtEase::suppressWarnings();
-		$result = fseek( $this->file, $offset );
-		AtEase::restoreWarnings();
+		// phpcs:ignore Generic.PHP.NoSilencedErrors.Discouraged
+		$result = @fseek( $this->file, $offset );
 		if ( $result !== 0 ) {
 			$this->error( "unable to seek to offset $offset", self::ERROR_SEEK );
 		}
diff --git a/includes/libs/mime/MimeAnalyzer.php b/includes/libs/mime/MimeAnalyzer.php
index 8d27ce34e7a4..72855cf54bd0 100644
--- a/includes/libs/mime/MimeAnalyzer.php
+++ b/includes/libs/mime/MimeAnalyzer.php
@@ -1,7 +1,5 @@
 <?php
 /**
- * Module defining helper functions for detecting and dealing with MIME types.
- *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -27,9 +25,16 @@ use Wikimedia\Mime\MimeMap;
 use Wikimedia\Mime\MimeMapMinimal;
 
 /**
- * Implements functions related to MIME types such as detection and mapping to file extension
+ * @defgroup Mime Mime
+ *
+ * @ingroup Media
+ */
+
+/**
+ * Detect MIME types of a file by mapping file extensions or parsing file contents.
  *
  * @since 1.28
+ * @ingroup Mime
  */
 class MimeAnalyzer implements LoggerAwareInterface {
 	/** @var string */
diff --git a/includes/libs/mime/MimeMap.php b/includes/libs/mime/MimeMap.php
index 36eaeaab6c7d..2d5259798127 100644
--- a/includes/libs/mime/MimeMap.php
+++ b/includes/libs/mime/MimeMap.php
@@ -21,10 +21,10 @@
 namespace Wikimedia\Mime;
 
 /**
- * MimeMap defines the mapping of MIME types to file extensions and media
- * types.
+ * Map of MIME types to file extensions and media types.
  *
  * @internal
+ * @ingroup Mime
  */
 class MimeMap {
 	/** @var array Map of MIME types to an array of file extensions */
diff --git a/includes/libs/mime/MimeMapMinimal.php b/includes/libs/mime/MimeMapMinimal.php
index ddff0279a437..967dd2d0a955 100644
--- a/includes/libs/mime/MimeMapMinimal.php
+++ b/includes/libs/mime/MimeMapMinimal.php
@@ -21,13 +21,13 @@
 namespace Wikimedia\Mime;
 
 /**
- * MimeMapMinimal defines a core set of MIME types that cannot be overridden by
- * configuration.
+ * Built-in MIME types that cannot be overridden by site configuration.
  *
- * This class exists for backward compatibility ONLY. New MIME types should be
+ * This class exists for backward compatibility only. New MIME types must be
  * added to MimeMap instead.
  *
  * @internal
+ * @ingroup Mime
  */
 class MimeMapMinimal {
 	public const MIME_EXTENSIONS = [
diff --git a/includes/libs/mime/XmlTypeCheck.php b/includes/libs/mime/XmlTypeCheck.php
index 035057fed8e4..e8c890a62a88 100644
--- a/includes/libs/mime/XmlTypeCheck.php
+++ b/includes/libs/mime/XmlTypeCheck.php
@@ -1,12 +1,5 @@
 <?php
 /**
- * XML syntax and type checker.
- *
- * Since 1.24.2, it uses XMLReader instead of xml_parse, which gives us
- * more control over the expansion of XML entities. When passed to the
- * callback, entities will be fully expanded, but may report the XML is
- * invalid if expanding the entities are likely to cause a DoS.
- *
  * This program is free software; you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
  * the Free Software Foundation; either version 2 of the License, or
@@ -25,6 +18,18 @@
  * @file
  */
 
+/**
+ * XML syntax and type checker.
+ *
+ * Since MediaWiki 1.24.2, this uses XMLReader instead of xml_parse, which gives us
+ * more control over the expansion of XML entities. When passed to the
+ * callback, entities will be fully expanded, but may report the XML is
+ * invalid if expanding the entities are likely to cause a DoS.
+ *
+ * @newable
+ * @since 1.12.0
+ * @ingroup Mime
+ */
 class XmlTypeCheck {
 	/**
 	 * @var bool|null Will be set to true or false to indicate whether the file is
diff --git a/includes/libs/mime/defines.php b/includes/libs/mime/defines.php
index 185765daa919..e6202ac0b7d6 100644
--- a/includes/libs/mime/defines.php
+++ b/includes/libs/mime/defines.php
@@ -16,6 +16,7 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
+ * @ingroup Mime
  */
 
 /** @{
-- 
cgit v1.2.3