From a4813c26f38089be95b88199b91a6548039ae0f0 Mon Sep 17 00:00:00 2001
From: Thiemo Kreuz <thiemo.kreuz@wikimedia.de>
Date: Thu, 3 Sep 2020 12:06:10 +0200
Subject: [PATCH] Add and update soft PHPDoc type hints

In detail:
* Callers don't need to know that the return value can be a
  TemplateDataCompressedBlob. All relevant stuff is declared in
  the base class.
* It's not relevant which internal method returned the status.
  It's just the status of the object after it was constructed.
* "stdClass" is more specific. "object" includes more stuff
  which can't be returned here.
* Avoid duplication and use @inheritDoc instead.

Change-Id: I68878a5b26ecd566fbea88b513ee697b45769659
---
 includes/TemplateDataBlob.php           | 12 ++++++------
 includes/TemplateDataCompressedBlob.php |  5 +----
 2 files changed, 7 insertions(+), 10 deletions(-)

diff --git a/includes/TemplateDataBlob.php b/includes/TemplateDataBlob.php
index 45cda16a..02c1e4fd 100644
--- a/includes/TemplateDataBlob.php
+++ b/includes/TemplateDataBlob.php
@@ -32,7 +32,7 @@ class TemplateDataBlob {
 	protected $json = null;
 
 	/**
-	 * @var Status Cache of TemplateDataBlob::parse
+	 * @var Status
 	 */
 	protected $status;
 
@@ -43,8 +43,7 @@ class TemplateDataBlob {
 	 *
 	 * @param IDatabase $db
 	 * @param string $json
-	 * @return TemplateDataBlob|TemplateDataCompressedBlob
-	 * @throws Exception
+	 * @return TemplateDataBlob
 	 */
 	public static function newFromJSON( $db, $json ) {
 		if ( $db->getType() === 'mysql' ) {
@@ -80,7 +79,7 @@ class TemplateDataBlob {
 	 *
 	 * @param IDatabase $db
 	 * @param string $json
-	 * @return TemplateDataBlob or TemplateDataCompressedBlob
+	 * @return TemplateDataBlob
 	 */
 	public static function newFromDatabase( $db, $json ) {
 		// Handle GZIP compression. \037\213 is the header for GZIP files.
@@ -613,7 +612,7 @@ class TemplateDataBlob {
 	}
 
 	/**
-	 * @return object
+	 * @return stdClass
 	 */
 	public function getData() {
 		// Return deep clone so callers can't modify data. Needed for getDataInLanguage().
@@ -626,7 +625,7 @@ class TemplateDataBlob {
 	 * appropriate language.
 	 *
 	 * @param string $langCode Preferred language
-	 * @return object
+	 * @return stdClass
 	 */
 	public function getDataInLanguage( $langCode ) {
 		$data = $this->getData();
@@ -701,6 +700,7 @@ class TemplateDataBlob {
 			$formatMsg = null;
 		} elseif ( isset( self::FORMATS[$data->format] ) ) {
 			$formatMsg = $data->format;
+			'@phan-var string $formatMsg';
 			$icon = 'template-format-' . $formatMsg;
 		} else {
 			$formatMsg = 'custom';
diff --git a/includes/TemplateDataCompressedBlob.php b/includes/TemplateDataCompressedBlob.php
index 76aad521..91897d62 100644
--- a/includes/TemplateDataCompressedBlob.php
+++ b/includes/TemplateDataCompressedBlob.php
@@ -23,10 +23,7 @@ class TemplateDataCompressedBlob extends TemplateDataBlob {
 	protected $jsonDB = null;
 
 	/**
-	 * Parse the data, normalise it and validate it.
-	 *
-	 * See Specification.md for the expected format of the JSON object.
-	 * @return Status
+	 * @inheritDoc
 	 */
 	protected function parse() {
 		$status = parent::parse();