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

@@ -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 );
 		}

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 */

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 */

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 = [

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

includes/libs/mime/defines.php

@@ -16,6 +16,7 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
+ * @ingroup Mime
  */
 
 /** @{

includes/media/MediaHandler.php

@@ -16,7 +16,6 @@
  * http://www.gnu.org/copyleft/gpl.html
  *
  * @file
- * @ingroup Media
  */
 
 use MediaWiki\HookContainer\HookRunner;
@@ -35,7 +34,6 @@ use MediaWiki\Status\Status;
  * Base media handler class
  *
  * @stable to extend
- *
  * @ingroup Media
  */
 abstract class MediaHandler {

tests/phpunit/unit/includes/libs/mime/MSCompoundFileReaderTest.php

@@ -21,6 +21,7 @@ use PHPUnit\Framework\TestCase;
 
 /**
  * @group Media
+ * @group Mime
  * @covers \MSCompoundFileReader
  */
 class MSCompoundFileReaderTest extends TestCase {

tests/phpunit/unit/includes/libs/mime/MimeAnalyzerTest.php

@@ -10,6 +10,7 @@ use Wikimedia\TestingAccessWrapper;
 
 /**
  * @group Media
+ * @group Mime
  * @covers \MimeAnalyzer
  */
 class MimeAnalyzerTest extends TestCase {