Added more specific PHPDoc to interfaces (sonata-project#5664)

src/Admin/AdminInterface.php

@@ -22,6 +22,7 @@
 use Sonata\AdminBundle\Object\MetadataInterface;
 use Sonata\AdminBundle\Security\Handler\SecurityHandlerInterface;
 use Sonata\AdminBundle\Translator\LabelTranslatorStrategyInterface;
+use Sonata\Exporter\Source\SourceIteratorInterface;
 use Sonata\Form\Validator\ErrorElement;
 use Symfony\Component\Form\FormBuilderInterface;
 use Symfony\Component\Form\FormInterface;
@@ -376,7 +377,7 @@ public function getExportFormats();
     /**
      * Returns SourceIterator.
      *
-     * @return \Sonata\Exporter\Source\SourceIteratorInterface
+     * @return SourceIteratorInterface
      */
     public function getDataSourceIterator();
 
@@ -626,6 +627,8 @@ public function getCurrentChild();
     public function getTranslationLabel($label, $context = '', $type = '');
 
     /**
+     * @param object $object
+     *
      * @return MetadataInterface
      */
     public function getObjectMetadata($object);
@@ -636,18 +639,6 @@ public function getObjectMetadata($object);
     public function getListModes();
 
     /**
-     * @param string $mode
-     */
-    public function setListMode($mode);
-
-    /**
-     * return the list mode.
-     *
-     * @return string
-     */
-    public function getListMode();
-
-    /*
      * Check the current request is given route or not.
      *
      * TODO: uncomment this method before releasing 4.0
@@ -659,10 +650,20 @@ public function getListMode();
      */
     // public function isCurrentRoute(string $name, ?string $adminCode = null): bool;
 
+    /**
+     * @param string $mode
+     */
+    public function setListMode($mode);
+
+    /**
+     * @return string
+     */
+    public function getListMode();
+
     /*
      * Configure buttons for an action
      */
-    // public function configureActionButtons(string $action, ?object $object = null): void;
+    // public function configureActionButtons(string $action, ?object $object = null): array;
 
     //TODO: uncomment this method for 4.0
     /*
@@ -678,7 +679,7 @@ public function getListMode();
 //    public function showMosaicButton(bool $isShown): void;
 
     /*
-     * Checks if a filter type is set to a default valu
+     * Checks if a filter type is set to a default value
      */
 //    NEXT_MAJOR: uncomment this method in 4.0
     // public function isDefaultFilter(string $name): bool;

src/Admin/FieldDescriptionInterface.php

@@ -117,7 +117,7 @@ public function setParent(AdminInterface $parent);
     /**
      * return the parent Admin (only used in nested admin).
      *
-     * @return AdminInterface
+     * @return AdminInterface|null
      */
     public function getParent();
 
@@ -211,7 +211,6 @@ public function getAdmin();
     /**
      * merge option values related to the provided option name.
      *
-     *
      * @param string $name
      *
      * @throws \RuntimeException

src/Builder/DatagridBuilderInterface.php

@@ -23,8 +23,6 @@
 interface DatagridBuilderInterface extends BuilderInterface
 {
     /**
-     * @abstract
-     *
      * @param string $type
      */
     public function addFilter(

src/Builder/FormContractorInterface.php

@@ -24,14 +24,9 @@
  */
 interface FormContractorInterface extends BuilderInterface
 {
-    /**
-     * @abstract
-     */
     public function __construct(FormFactoryInterface $formFactory);
 
     /**
-     * @abstract
-     *
      * @param string $name
      *
      * @return FormBuilder
@@ -41,8 +36,6 @@ public function getFormBuilder($name, array $options = []);
     /**
      * Should provide Symfony form options.
      *
-     * @abstract
-     *
      * @param string $type
      *
      * @return array

src/Builder/ShowBuilderInterface.php

@@ -25,8 +25,6 @@ interface ShowBuilderInterface extends BuilderInterface
     public function getBaseList(array $options = []);
 
     /**
-     * @abstract
-     *
      * @param string|null $type
      */
     public function addField(

src/Datagrid/ProxyQueryInterface.php

@@ -44,19 +44,19 @@ public function execute(array $params = [], $hydrationMode = null);
     public function setSortBy($parentAssociationMappings, $fieldMapping);
 
     /**
-     * @return mixed
+     * @return string
      */
     public function getSortBy();
 
     /**
-     * @param mixed $sortOrder
+     * @param string $sortOrder
      *
      * @return ProxyQueryInterface
      */
     public function setSortOrder($sortOrder);
 
     /**
-     * @return mixed
+     * @return array<string, string>
      */
     public function getSortOrder();
 
@@ -85,17 +85,17 @@ public function getFirstResult();
     public function setMaxResults($maxResults);
 
     /**
-     * @return mixed
+     * @return int|null
      */
     public function getMaxResults();
 
     /**
-     * @return mixed
+     * @return int
      */
     public function getUniqueParameterId();
 
     /**
-     * @return mixed
+     * @return string
      */
     public function entityJoin(array $associationMappings);
 }

src/Filter/FilterFactoryInterface.php

@@ -22,7 +22,7 @@ interface FilterFactoryInterface
      * @param string $name
      * @param string $type
      *
-     * @return mixed
+     * @return FilterInterface
      */
     public function create($name, $type, array $options = []);
 }

src/Guesser/TypeGuesserInterface.php

@@ -14,6 +14,7 @@
 namespace Sonata\AdminBundle\Guesser;
 
 use Sonata\AdminBundle\Model\ModelManagerInterface;
+use Symfony\Component\Form\Guess\Guess;
 
 /**
  * @author Thomas Rabaix <[email protected]>
@@ -24,7 +25,7 @@ interface TypeGuesserInterface
      * @param string $class
      * @param string $property
      *
-     * @return mixed
+     * @return Guess|null
      */
     public function guessType($class, $property, ModelManagerInterface $modelManager);
 }

src/Model/AuditReaderInterface.php

@@ -22,25 +22,33 @@ interface AuditReaderInterface
      * @param string $className
      * @param string $id
      * @param string $revision
+     *
+     * @return object
      */
     public function find($className, $id, $revision);
 
     /**
      * @param string $className
      * @param int    $limit
      * @param int    $offset
+     *
+     * @return object[]
      */
     public function findRevisionHistory($className, $limit = 20, $offset = 0);
 
     /**
      * @param string $classname
      * @param string $revision
+     *
+     * @return object
      */
     public function findRevision($classname, $revision);
 
     /**
      * @param string $className
      * @param string $id
+     *
+     * @return object[]
      */
     public function findRevisions($className, $id);
 
@@ -49,6 +57,8 @@ public function findRevisions($className, $id);
      * @param int    $id
      * @param int    $oldRevision
      * @param int    $newRevision
+     *
+     * @return array
      */
     public function diff($className, $id, $oldRevision, $newRevision);
 }

src/Model/ModelManagerInterface.php

@@ -156,7 +156,7 @@ public function getUrlsafeIdentifier($model);
      *
      * @param string $class
      *
-     * @return mixed
+     * @return object
      */
     public function getModelInstance($class);
 
@@ -170,26 +170,24 @@ public function getModelCollectionInstance($class);
     /**
      * Removes an element from the collection.
      *
-     * @param mixed $collection
-     * @param mixed $element
+     * @param array  $collection
+     * @param object $element
      */
     public function collectionRemoveElement(&$collection, &$element);
 
     /**
      * Add an element from the collection.
      *
-     * @param mixed $collection
-     * @param mixed $element
-     *
-     * @return mixed
+     * @param array  $collection
+     * @param object $element
      */
     public function collectionAddElement(&$collection, &$element);
 
     /**
      * Check if the element exists in the collection.
      *
-     * @param mixed $collection
-     * @param mixed $element
+     * @param array  $collection
+     * @param object $element
      *
      * @return bool
      */
@@ -198,23 +196,21 @@ public function collectionHasElement(&$collection, &$element);
     /**
      * Clear the collection.
      *
-     * @param mixed $collection
-     *
-     * @return mixed
+     * @param array $collection
      */
     public function collectionClear(&$collection);
 
     /**
      * Returns the parameters used in the columns header.
      *
-     * @return array
+     * @return array<string, mixed>
      */
     public function getSortParameters(FieldDescriptionInterface $fieldDescription, DatagridInterface $datagrid);
 
     /**
      * @param string $class
      *
-     * @return array
+     * @return array<string, string>
      */
     public function getDefaultSortValues($class);
 
@@ -250,14 +246,14 @@ public function getDataSourceIterator(
     /**
      * @param string $class
      *
-     * @return array
+     * @return string[]
      */
     public function getExportFields($class);
 
     /**
      * @param int $page
      *
-     * @return mixed
+     * @return array<string, mixed>
      */
     public function getPaginationParameters(DatagridInterface $datagrid, $page);