Unify variable function params docs

Author: thiemowmde

RELEASE-NOTES.md

@@ -2,6 +2,7 @@
 
 ## Version 3.0.0 (dev)
 
+* `ReferenceList::addNewReference` and `Statement::addNewReference` support an array of Snaks now
 * The concept of `Claim` is no longer modelled
 	* The `Claim` class itself has been removed, though `Claim` is now a temporary alias for `Statement`
 	* `Claim::RANK_TRUTH` have been removed

src/ReferenceList.php

@@ -6,7 +6,6 @@
 use InvalidArgumentException;
 use Traversable;
 use Wikibase\DataModel\Snak\Snak;
-use Wikibase\DataModel\Snak\SnakList;
 
 /**
  * List of Reference objects.
@@ -72,27 +71,30 @@ public function addReference( Reference $reference, $index = null ) {
 
 	/**
 	 * @see SplObjectStorage::attach
+	 *
 	 * @param Reference $reference
-	 * @param mixed $data
+	 * @param mixed $data Unused in the ReferenceList class.
 	 */
 	public function attach( $reference, $data = null ) {
 		if ( !$reference->isEmpty() ) {
 			parent::attach( $reference, $data );
 		}
 	}
 
-	// @codingStandardsIgnoreStart
 	/**
 	 * @since 1.1
 	 *
-	 * @param Snak $snak
-	 * @param Snak [$snak2, ...]
+	 * @param Snak[]|Snak $snaks
+	 * @param Snak [$snak2,...]
 	 *
 	 * @throws InvalidArgumentException
 	 */
-	public function addNewReference( Snak $snak /* Snak, ... */ ) {
-		// @codingStandardsIgnoreEnd
-		$this->addReference( new Reference( new SnakList( func_get_args() ) ) );
+	public function addNewReference( $snaks = array() /*...*/ ) {
+		if ( $snaks instanceof Snak ) {
+			$snaks = func_get_args();
+		}
+
+		$this->addReference( new Reference( $snaks ) );
 	}
 
 	/**

src/Statement/Statement.php

@@ -172,18 +172,20 @@ public function setReferences( ReferenceList $references ) {
 		$this->references = $references;
 	}
 
-	// @codingStandardsIgnoreStart
 	/**
 	 * @since 2.0
 	 *
-	 * @param Snak $snak
-	 * @param Snak [$snak2, ...]
+	 * @param Snak[]|Snak $snaks
+	 * @param Snak [$snak2,...]
 	 *
 	 * @throws InvalidArgumentException
 	 */
-	public function addNewReference( Snak $snak /* Snak, ... */ ) {
-		// @codingStandardsIgnoreEnd
-		$this->references->addReference( new Reference( new SnakList( func_get_args() ) ) );
+	public function addNewReference( $snaks = array() /*...*/ ) {
+		if ( $snaks instanceof Snak ) {
+			$snaks = func_get_args();
+		}
+
+		$this->references->addNewReference( $snaks );
 	}
 
 	/**

src/Statement/StatementList.php

@@ -36,11 +36,11 @@ class StatementList implements IteratorAggregate, Comparable, Countable {
 
 	/**
 	 * @param Statement[]|Traversable|Statement $statements
-	 * @param Statement [$statement2, ...]
+	 * @param Statement [$statement2,...]
 	 *
 	 * @throws InvalidArgumentException
 	 */
-	public function __construct( $statements = array() /* Statement, ... */ ) {
+	public function __construct( $statements = array() /*...*/ ) {
 		if ( $statements instanceof Statement ) {
 			$statements = func_get_args();
 		}

tests/unit/ReferenceListTest.php

@@ -8,7 +8,6 @@
 use Wikibase\DataModel\Reference;
 use Wikibase\DataModel\ReferenceList;
 use Wikibase\DataModel\Snak\PropertyNoValueSnak;
-use Wikibase\DataModel\Snak\PropertyValueSnak;
 use Wikibase\DataModel\Snak\SnakList;
 
 /**
@@ -311,20 +310,26 @@ public function testGivenOneSnak_addNewReferenceAddsSnak() {
 
 	public function testGivenMultipleSnaks_addNewReferenceAddsThem() {
 		$references = new ReferenceList();
+		$snak1 = new PropertyNoValueSnak( 1 );
+		$snak2 = new PropertyNoValueSnak( 3 );
+		$snak3 = new PropertyNoValueSnak( 2 );
 
-		$references->addNewReference(
-			new PropertyNoValueSnak( 1 ),
-			new PropertyNoValueSnak( 3 ),
-			new PropertyNoValueSnak( 2 )
-		);
+		$references->addNewReference( $snak1, $snak2, $snak3 );
 
-		$expectedSnaks = array(
+		$expectedSnaks = array( $snak1, $snak2, $snak3 );
+		$this->assertTrue( $references->hasReference( new Reference( $expectedSnaks ) ) );
+	}
+
+	public function testGivenAnArrayOfSnaks_addNewReferenceAddsThem() {
+		$references = new ReferenceList();
+		$snaks = array(
 			new PropertyNoValueSnak( 1 ),
 			new PropertyNoValueSnak( 3 ),
 			new PropertyNoValueSnak( 2 )
 		);
 
-		$this->assertTrue( $references->hasReference( new Reference( new SnakList( $expectedSnaks ) ) ) );
+		$references->addNewReference( $snaks );
+		$this->assertTrue( $references->hasReference( new Reference( $snaks ) ) );
 	}
 
 	public function testGivenNoneSnak_addNewReferenceThrowsException() {

tests/unit/Statement/StatementTest.php

@@ -151,11 +151,26 @@ public function testSetReferences( Statement $statement ) {
 	/**
 	 * @dataProvider instanceProvider
 	 */
-	public function testAddNewReference( Statement $statement ) {
+	public function testAddNewReferenceWithVariableArgumentsSyntax( Statement $statement ) {
 		$snak1 = new PropertyNoValueSnak( 256 );
 		$snak2 = new PropertySomeValueSnak( 42 );
 		$statement->addNewReference( $snak1, $snak2 );
-		$this->assertTrue( $statement->getReferences()->hasReference( new Reference( array( $snak1, $snak2 ) ) ) );
+
+		$expectedSnaks = array( $snak1, $snak2 );
+		$this->assertTrue( $statement->getReferences()->hasReference( new Reference( $expectedSnaks ) ) );
+	}
+
+	/**
+	 * @dataProvider instanceProvider
+	 */
+	public function testAddNewReferenceWithAnArrayOfSnaks( Statement $statement ) {
+		$snaks = array(
+			new PropertyNoValueSnak( 256 ),
+			new PropertySomeValueSnak( 42 ),
+		);
+		$statement->addNewReference( $snaks );
+
+		$this->assertTrue( $statement->getReferences()->hasReference( new Reference( $snaks ) ) );
 	}
 
 	/**