yiisoft · vjik · Jan 8, 2026 · Jan 7, 2026 · Jan 7, 2026 · Jan 7, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,8 +2,8 @@
 
 ## 1.0.1 under development
 
-- no changes in this release.
+- Bug #527: Fix PHPDoc tags `@see` (@mspirkov)
 
 ## 1.0.0 December 09, 2025
 
-- Initial release.
+- Initial release.
diff --git a/src/AbstractActiveRecord.php b/src/AbstractActiveRecord.php
@@ -81,7 +81,7 @@

    public function equals(ActiveRecordInterface $record): bool
    {
        if ($this->isNew() || $record->isNew()) {
            return false;
        }

@@ -148,7 +148,7 @@
        return match (count($keys)) {
            1 => $this->oldValues[$keys[0]] ?? null,
            0 => throw new LogicException(
                static::class . ' does not have a primary key. You should either define a primary key for '
                . $this->tableName() . ' table or override the primaryKey() method.',
            ),
            default => throw new LogicException(
@@ -163,7 +163,7 @@

        if (empty($keys)) {
            throw new LogicException(
                static::class . ' does not have a primary key. You should either define a primary key for '
                . $this->tableName() . ' table or override the primaryKey() method.',
            );
        }
@@ -188,7 +188,7 @@
        return match (count($keys)) {
            1 => $this->get($keys[0]),
            0 => throw new LogicException(
                static::class . ' does not have a primary key. You should either define a primary key for '
                . $this->tableName() . ' table or override the primaryKey() method.',
            ),
            default => throw new LogicException(
@@ -794,7 +794,7 @@
     /**
      * Internal method to insert or update a record in the database.
      *
-     * @see upsert()
+     * @see AbstractActiveRecord::upsert()
      */
     abstract protected function upsertInternal(
         ?array $insertProperties = null,
@@ -823,8 +823,8 @@
      * @psalm-param ModelClass $modelClass
      * @psalm-param array<string, string> $link
      *
-     * {@see hasOne()}
-     * {@see hasMany()}
+     * @see AbstractActiveRecord::hasOne()
+     * @see AbstractActiveRecord::hasMany()
      */
     protected function createRelationQuery(
         ActiveRecordInterface|string $modelClass,
@@ -835,12 +835,12 @@
     }
 
     /**
-     * {@see delete()}
-     *
      * @throws Exception
      * @throws Throwable
      *
      * @return int The number of rows deleted.
+     *
+     * @see AbstractActiveRecord::delete()
      */
     protected function deleteInternal(): int
     {
@@ -875,7 +875,7 @@
      * You may specify the properties to be returned as list of name or name-value pairs.
      * If name-value pair specified, the corresponding property values will be modified.
      *
-     * Only the {@see newValues() changed property values} will be returned.
+     * Only the {@see AbstractActiveRecord::newValues() changed property values} will be returned.
      *
      * @param array|null $properties List of property names or name-values pairs that need to be returned.
      * Defaults to `null`, meaning all changed property values will be returned.
@@ -911,7 +911,7 @@
      *
      * @return bool Whether refresh was successful.
      *
-     * {@see refresh()}
+     * @see AbstractActiveRecord::refresh()
      */
     protected function refreshInternal(array|ActiveRecordInterface|null $record = null): bool
     {
@@ -931,14 +931,14 @@
     }
 
     /**
-     * {@see update()}
-     *
      * @param array|null $properties Property names or name-values pairs to update, `null` means all properties.
      *
      * @throws Exception
      * @throws NotSupportedException
      *
      * @return int The number of rows affected.
+     *
+     * @see AbstractActiveRecord::update()
      */
     protected function updateInternal(?array $properties = null): int
     {

diff --git a/src/ActiveQuery.php b/src/ActiveQuery.php
@@ -15,6 +15,7 @@
 use Yiisoft\ActiveRecord\Internal\RelationPopulator;
 use Yiisoft\ActiveRecord\Internal\TableNameAndAliasResolver;
 use Yiisoft\ActiveRecord\Internal\Typecaster;
+use Yiisoft\ActiveRecord\Trait\RepositoryTrait;
 use Yiisoft\Db\Command\CommandInterface;
 use Yiisoft\Db\Exception\Exception;
 use Yiisoft\Db\Exception\InvalidConfigException;
@@ -47,35 +48,36 @@
  *
  * An ActiveQuery can be a normal query or be used in a relational context.
  *
- * ActiveQuery instances are usually created by {@see findOne()}, {@see findBySql()}, {@see findAll()}.
+ * ActiveQuery instances are usually created by {@see RepositoryTrait::findOne()},
+ * {@see RepositoryTrait::findBySql()}, {@see RepositoryTrait::findAll()}.
  *
- * Relational queries are created by {@see ActiveRecord::hasOne()} and {@see ActiveRecord::hasMany()}.
+ * Relational queries are created by {@see ActiveRecordInterface::hasOne()} and {@see ActiveRecordInterface::hasMany()}.
  *
  * Normal Query
  * ------------
  *
  * ActiveQuery mainly provides the following methods to retrieve the query results:
  *
- * - {@see one()}: returns a single record populated with the first row of data.
- * - {@see all()}: returns all records based on the query results.
- * - {@see count()}: returns the number of records.
- * - {@see sum()}: returns the sum over the specified column.
- * - {@see average()}: returns the average over the specified column.
- * - {@see min()}: returns the min over the specified column.
- * - {@see max()}: returns the max over the specified column.
- * - {@see scalar()}: returns the value of the first column in the first row of the query result.
- * - {@see column()}: returns the value of the first column in the query result.
- * - {@see exists()}: returns a value indicating whether the query result has data or not.
+ * - {@see Query::one()}: returns a single record populated with the first row of data.
+ * - {@see Query::all()}: returns all records based on the query results.
+ * - {@see Query::count()}: returns the number of records.
+ * - {@see Query::sum()}: returns the sum over the specified column.
+ * - {@see Query::average()}: returns the average over the specified column.
+ * - {@see Query::min()}: returns the min over the specified column.
+ * - {@see Query::max()}: returns the max over the specified column.
+ * - {@see Query::scalar()}: returns the value of the first column in the first row of the query result.
+ * - {@see Query::column()}: returns the value of the first column in the query result.
+ * - {@see Query::exists()}: returns a value indicating whether the query result has data or not.
  *
- * Because ActiveQuery extends from {@see Query}, one can use query methods, such as {@see where()}, {@see orderBy()} to
- * customize the query options.
+ * Because ActiveQuery extends from {@see Query}, one can use query methods, such as {@see Query::where()},
+ * {@see Query::orderBy()} to customize the query options.
  *
  * ActiveQuery also provides the following more query options:
  *
- * - {@see with()}: list of relations that this query should be performed with.
- * - {@see joinWith()}: reuse a relation query definition to add a join to a query.
- * - {@see indexBy()}: the name of the column by which the query result should be indexed.
- * - {@see asArray()}: whether to return each record as an array.
+ * - {@see ActiveQuery::with()}: list of relations that this query should be performed with.
+ * - {@see ActiveQuery::joinWith()}: reuse a relation query definition to add a join to a query.
+ * - {@see Query::indexBy()}: the name of the column by which the query result should be indexed.
+ * - {@see ActiveQuery::asArray()}: whether to return each record as an array.
  *
  * These options can be configured using methods of the same name. For example:
  *
@@ -89,17 +91,19 @@
  *
  * In relational context, ActiveQuery represents a relation between two Active Record classes.
  *
- * Relational ActiveQuery instances are usually created by calling {@see ActiveRecord::hasOne()} and
- * {@see ActiveRecord::hasMany()}. An Active Record class declares a relation by defining a getter method which calls
+ * Relational ActiveQuery instances are usually created by calling {@see ActiveRecordInterface::hasOne()} and
+ * {@see ActiveRecordInterface::hasMany()}. An Active Record class declares a relation by defining a getter method which calls
  * one of the above methods and returns the created ActiveQuery object.
  *
- * A relation is specified by {@see link()} which represents the association between columns of different tables; and
- * the multiplicity of the relation is indicated by {@see multiple()}.
+ * A relation is specified by {@see ActiveQuery::link()} which represents the association between columns
+ * of different tables; and the multiplicity of the relation is indicated by {@see ActiveQuery::multiple()}.
  *
- * If a relation involves a junction table, it may be specified by {@see via()} or {@see viaTable()} method.
+ * If a relation involves a junction table, it may be specified by {@see ActiveQuery::via()}
+ * or {@see ActiveQuery::viaTable()} method.
  *
- * These methods may only be called in a relational context. The same is true for {@see inverseOf()}, which marks a relation
- * as inverse of another relation and {@see onCondition()} which adds a condition that is to be added to relational
+ * These methods may only be called in a relational context. The same is true for
+ * {@see ActiveQuery::inverseOf()}, which marks a relation as inverse of another relation
+ * and {@see ActiveQuery::on()} which adds a condition that is to be added to relational
  * query join condition.
  *
  * @psalm-type ModelClass = ActiveRecordInterface|class-string<ActiveRecordInterface>
@@ -140,7 +144,7 @@ class ActiveQuery extends Query implements ActiveQueryInterface
      *
      * This property is only used in relational context.
      *
-     * @see inverseOf()
+     * @see ActiveQuery::inverseOf()
      */
     private ?string $inverseOf = null;
 
@@ -638,7 +642,7 @@ public function link(array $value): static
     }
 
     /**
-     * Queries a scalar value by setting {@see select()} first.
+     * Queries a scalar value by setting {@see Query::select()} first.
      *
      * Restores the value of select to make this query reusable.
      *
@@ -786,8 +790,8 @@ private function populateOne(array $row): ActiveRecordInterface|array
     /**
      * Finds records corresponding to one or multiple relations and populates them into the primary models.
      *
-     * @param array $with a list of relations that this query should be performed with. Please refer to {@see with()}
-     * for details about specifying this parameter.
+     * @param array $with a list of relations that this query should be performed with. Please refer
+     * to {@see ActiveQuery::with()} for details about specifying this parameter.
      * @param ActiveRecordInterface[]|array[] $models the primary models (can be either AR instances or arrays)
      *
      * @throws Exception
@@ -865,7 +869,8 @@ private function normalizeRelations(ActiveRecordInterface $model, array $with):
     /**
      * If applicable, populate the query's primary model into the related records' inverse relationship.
      *
-     * @param ActiveRecordInterface[]|array[] $result the array of related records as generated by {@see populate()}
+     * @param ActiveRecordInterface[]|array[] $result the array of related records as generated
+     * by {@see ActiveQuery::populate()}
      *
      * @throws InvalidConfigException
      *