A magic property can be declared several time without error.
With inheritance, a magic property can't be overridden, it's just duplicated.

Expected behavior

If a magic property is defined twice, there should be a warning.
If a magic property is overridden, the override should replace instead of just being added.

Actual behavior

A magic property can be documented several times.

Steps to reproduce the problem

1. In an empty folder create the four following classes in respectively BaseClass.php, BaseValueClass.php, HeirClass.php, and HeirValueClass.php.

<?php

/**
 * @property-read BaseValueClass $value
 * @property-read string $value
 */
class BaseClass
{
    public function __construct(array $properties = [])
    {
        foreach ($properties as $property => $value) {
            $this->$property = $value;
        }
    }

    public function __get($property)
    {
        if (property_exists($this, $property)) {
            return $this->$property;
        }
    }
}

<?php

class BaseValueClass
{
}

<?php

/**
 * @property-read HeirValueClass $value
 */
class HeirClass extends BaseClass
{
}

<?php

class HeirValueClass extends BaseValueClass
{
}

2. Generate the documentation from this folder.

curl -LO "https://github.com/phpDocumentor/phpDocumentor/releases/download/v3.4.3/phpDocumentor.phar";
php phpDocumentor.phar;

3. Open HeirClass documentation (./.phpdoc/build/classes/HeirClass.html) and see the issues:

There is 3 $value in the Properties section:

• $value: HeirValueClass
• $value: BaseValueClass
• $value: string

Two problems:

• The double declaration of $value in BaseClass is just replicated in the documentation. No related warning was thrown during the built.
• The redefinition of $value in HeirClass is added to the existing properties instead of overriding them.

Your environment

• Version used: 3.4.3
• phpDocumentor.phar downloaded and used as-is
• PHP 8.3.6 (cli) (built: Apr 10 2024 14:21:20) (NTS)
• macOS Sonoma 14.4.1 (23E224)