How does @var work in phpDoc when specifying an interface?

Question

phpDocumentor

How it works @varwhen specifying a class is clear to me, but what about the interface?

/**
 * Модель продукта
 *
 * @var \carono\exchange1c\interfaces\ProductInterface
 */
 public $productClass;

UPD:
Call code

/**
     * @return ProductInterface
     */
    protected function getProductClass()
    {
        return $this->exModule->productClass;
    }

The exModule property contains an object of this class

<?php

namespace app\modules\exchange\models;

use carono\exchange1c\helpers\ModuleHelper;
use yii\helpers\FileHelper;
use yii\helpers\Inflector;
use yii\web\IdentityInterface;
use Yii;

/**
 * exchange module definition class
 */
class ExchangeModule extends \yii\base\Module
{
    /**
     * @inheritdoc
     */
    public $controllerNamespace = 'app\modules\exchange\models';
    /**
     * Модель продукта
     *
     * @var \carono\exchange1c\interfaces\ProductInterface
     */
    public $productClass;
    /**
     * Модель предложения
     *
     * @var \carono\exchange1c\interfaces\OfferInterface
     */
    public $offerClass;
    /**
     * Модель документа
     *
     * @var \carono\exchange1c\interfaces\DocumentInterface
     */
    public $documentClass;
    /**
     * Модель группы продукта
     *
     * @var \carono\exchange1c\interfaces\GroupInterface
     */
    public $groupClass;
    /**
     * Модель пользователя
     *
     * @var \carono\exchange1c\interfaces\PartnerInterface
     */
    public $partnerClass;
    /**
     * Модель склада
     *
     * @var \carono\exchange1c\interfaces\WarehouseInterface
     */
    public $warehouseClass;
    /**
     * Обмен документами
     *
     * @var bool
     */
    public $exchangeDocuments = false;
    /**
     * Режим отладки - сохраняем xml файлы в runtime
     *
     * @var bool
     */
    public $debug = false;
    /**
     * При обмене используем архиватор, если расширения нет, то зачение не учитывается
     *
     * @var bool
     */
    public $useZip = true;
    /**
     * Папка, где будут сохранятся временные файлы
     *
     * @var string
     */
    public $tmpDir = '@runtime/1c_exchange';
    /**
     * При сохранении товара, используем валидацию или нет
     *
     * @var bool
     */
    public $validateModelOnSave = false;
    /**
     * Установка лимита выполнения скрипта
     *
     * @var int
     */
    public $timeLimit = 1800;
    /**
     * Установка лимита памяти скрипта
     *
     * @var mixed
     */
    public $memoryLimit;
    /**
     * Автоматическая установка правила для ссылки /1c_exchange.php
     *
     * @var bool
     */
    public $bootstrapUrlRule = true;

    /**
     * @var bool Добавлять правило в конец
     */
    public $appendRule = false;

    public $redactorModuleName = 'carono-exchange-redactor';
    /**
     * Функция авторизации пользователя
     * function ($login, $password): \yii\web\IdentityInterface|null
     *
     * @var \Closure
     */
    public $auth;

    private function loadRedactorModule()
    {
        $redactorClass = 'yii\redactor\widgets\Redactor';
        $moduleRedactorName = $this->redactorModuleName;
        if (class_exists($redactorClass) && !Yii::$app->getModule($moduleRedactorName)) {
            $routeName = Inflector::camel2id($moduleRedactorName);
            \Yii::$app->setModule($moduleRedactorName, [
                'class' => 'yii\redactor\RedactorModule',
                'uploadDir' => '@vendor/carono/yii2-1c-exchange/files/articles',
                'imageUploadRoute' => ["/$routeName/upload/image"],
                'fileUploadRoute' => ["/$routeName/upload/file"],
                'imageManagerJsonRoute' => ["/$routeName/upload/image-json"],
                'fileManagerJsonRoute' => ["/$routeName/upload/file-json"],
                'imageAllowExtensions' => ['jpg', 'png', 'gif'],
                'on beforeAction' => function () use ($moduleRedactorName) {
                    $redactor = \Yii::$app->getModule($moduleRedactorName);
                    $redactor->uploadUrl = '../file/article?file=';
                    \Yii::$app->setModule($moduleRedactorName, $redactor);
                }
            ]);
        }
    }

    /**
     * @return null|\yii\base\Module
     */
    public function getRedactor()
    {
        return Yii::$app->getModule($this->redactorModuleName);
    }

    /**
     * @inheritdoc
     */
    public function init()
    {
        if (!isset(\Yii::$app->i18n->translations['models'])) {
            \Yii::$app->i18n->translations['models'] = [
                'class' => 'yii\i18n\PhpMessageSource',
                'basePath' => '@app/messages',
                'sourceLanguage' => 'en',
            ];
        }
        $this->loadRedactorModule();
        parent::init();
    }

    public function getTmpDir($part = null)
    {
        $dir = \Yii::getAlias($this->tmpDir);
        if (!is_dir($dir)) {
            FileHelper::createDirectory($dir, 0777, true);
        }
        return $dir . ($part ? DIRECTORY_SEPARATOR . trim($part, '/\\') : '');
    }

    /**
     * @param $login
     * @param $password
     * @return null|IdentityInterface
     */
    public function auth($login, $password)
    {
        /**
         * @var $class \yii\web\IdentityInterface
         * @var IdentityInterface $user
         */
        $class = \Yii::$app->user->identityClass;
        if (method_exists($class, 'findByUsername')) {
            $user = $class::findByUsername($login);
            if ($user && method_exists($user, 'validatePassword') && $user->validatePassword($password)) {
                return $user;
            }
        }
        return null;
    }
}

Answer 1

When you specify @var App\Contracts\MyInterfacefor a property of some class, it makes you understand that you do not need anything else (except what is in the interface) in this class from this property.
Those. you can replace one implementation of this interface with another (throw an object of one class instead of another) and your code won't break.
For an IDE, this helps with substitution and code highlighting.
PS: Here's an example:

class ShapeHandler {
    /**
    * @var ShapeInterface
    */
    private $shape;

    public function __construct(ShapeInterface $shape) {
        $this->shape = $shape;
    }

    public function getShapeSize() : float {
        return $this->shape->getSize();
    }
}

interface ShapeInterface {
    public function getSize() : float;
}

class Circle implements ShapeInterface {
    private $radius;

    public function getSize() : float {
        return MATH_PI * pow($this->radius, 2);
    }

    public function getLength() : float {
        return MATH_PI * 2 * $this->radius;
    }
}

class Rectangle implements ShapeInterface {
    private $height;
    private $width;

    public function getSize() : float {
        return $this->height * $this->width;
    }

    public function getPerimetr() : float {
        return 2 * ($this->height + $this->width);
    }
}

$circle = new Circle();
$circle->setRadius(10);
$shapeHandler = new ShapeHandler($circle);
$shapeHandler->getShapeSize();

$rectangle = new Rectangle();
$rectangle->setHeight(5);
$rectangle->setWidth(20);
$shapeHandler = new ShapeHandler($rectangle);
$shapeHandler->getShapeSize();

Answer 2

Your question is not complete. Dig into the "@see" area

Answer 3

what is the point of this phpDoc even if it is not specified which variable contains the object that implements this interface? it's completely pointless.
but in general, because @var - after all, from the word variable - think about what a variable can be in php (I'll tell you - it's definitely not an interface).

Answer 4

It's like an adapter: when called, the external object is converted through the interface class into a new object that is understood by this particular class.