Merge pull request #750 from wmde/cleanDocs

Clarify documentation of …::newFromArray

Author: Ladsgroup

src/Entity/EntityIdValue.php

@@ -39,8 +39,6 @@ public function serialize() {
 	/**
 	 * @see Serializable::unserialize
 	 *
-	 * @since 0.5
-	 *
 	 * @param string $serialized
 	 *
 	 * @throws IllegalValueException
@@ -67,8 +65,6 @@ public function unserialize( $serialized ) {
 	/**
 	 * @see DataValue::getType
 	 *
-	 * @since 0.5
-	 *
 	 * @return string
 	 */
 	public static function getType() {
@@ -78,8 +74,6 @@ public static function getType() {
 	/**
 	 * @see DataValue::getSortKey
 	 *
-	 * @since 0.5
-	 *
 	 * @return string|float|int
 	 */
 	public function getSortKey() {
@@ -89,17 +83,13 @@ public function getSortKey() {
 	/**
 	 * @see DataValue::getValue
 	 *
-	 * @since 0.5
-	 *
 	 * @return self
 	 */
 	public function getValue() {
 		return $this;
 	}
 
 	/**
-	 * @since 0.5
-	 *
 	 * @return EntityId
 	 */
 	public function getEntityId() {
@@ -109,8 +99,6 @@ public function getEntityId() {
 	/**
 	 * @see DataValue::getArrayValue
 	 *
-	 * @since 0.5
-	 *
 	 * @return array
 	 */
 	public function getArrayValue() {
@@ -127,15 +115,19 @@ public function getArrayValue() {
 	}
 
 	/**
-	 * Constructs a new instance of the DataValue from the provided data.
-	 * This can round-trip with
-	 * @see getArrayValue
+	 * Constructs a new instance from the provided data. Required for @see DataValueDeserializer.
+	 * This is expected to round-trip with @see getArrayValue.
 	 *
-	 * @since 0.5
+	 * @deprecated since 7.1. Static DataValue::newFromArray constructors like this are
+	 *  underspecified (not in the DataValue interface), and misleadingly named (should be named
+	 *  newFromArrayValue). Instead, use DataValue builder callbacks in @see DataValueDeserializer.
 	 *
-	 * @param mixed $data
+	 * @param mixed $data Warning! Even if this is expected to be a value as returned by
+	 *  @see getArrayValue, callers of this specific newFromArray implementation can not guarantee
+	 *  this. This is not even guaranteed to be an array!
 	 *
-	 * @throws IllegalValueException
+	 * @throws IllegalValueException if $data is not in the expected format. Subclasses of
+	 *  InvalidArgumentException are expected and properly handled by @see DataValueDeserializer.
 	 * @return self
 	 */
 	public static function newFromArray( $data ) {

src/Statement/StatementListHolder.php

@@ -14,9 +14,6 @@
  */
 interface StatementListHolder extends StatementListProvider {
 
-	/**
-	 * @param StatementList $statements
-	 */
 	public function setStatements( StatementList $statements );
 
 }