Add @see location for macros & mixins to PhpDoc (#1054)

* Add @see location for macros & mixins to PhpDoc

* Fix CS

* Add entry to changelog

* Improve changelog entry

* Adjust CS

* Update CHANGELOG.md

Co-authored-by: Markus Podar <[email protected]>

Author: riesjart

CHANGELOG.md

@@ -8,6 +8,7 @@ All notable changes to this project will be documented in this file.
 ### Added
 - Fix phpdoc generate for custom cast with parameter [\#986 / artelkr](https://github.com/barryvdh/laravel-ide-helper/pull/986)
 - Created a possibility to add custom relation type [\#987 / efinder2](https://github.com/barryvdh/laravel-ide-helper/pull/987)
+- Added `@see` with macro/mixin definition location to PhpDoc [\#1054 / riesjart](https://github.com/barryvdh/laravel-ide-helper/pull/1054)
 
 ### Changed
 - Implement DeferrableProvider [\#914 / kon-shou](https://github.com/barryvdh/laravel-ide-helper/pull/914)

src/Macro.php

@@ -4,6 +4,7 @@
 
 use Barryvdh\Reflection\DocBlock;
 use Barryvdh\Reflection\DocBlock\Tag;
+use Illuminate\Support\Collection;
 
 class Macro extends Method
 {
@@ -33,6 +34,8 @@ protected function initPhpDoc($method)
     {
         $this->phpdoc = new DocBlock('/** */');
 
+        $this->addLocationToPhpDoc();
+
         // Add macro parameters
         foreach ($method->getParameters() as $parameter) {
             $type = $parameter->hasType() ? $parameter->getType()->getName() : 'mixed';
@@ -53,6 +56,24 @@ protected function initPhpDoc($method)
         }
     }
 
+    protected function addLocationToPhpDoc()
+    {
+        $enclosingClass = $this->method->getClosureScopeClass();
+
+        /** @var \ReflectionMethod $enclosingMethod */
+        $enclosingMethod = Collection::make($enclosingClass->getMethods())
+            ->first(function (\ReflectionMethod $method) {
+                return $method->getStartLine() <= $this->method->getStartLine()
+                    && $method->getEndLine() >= $this->method->getEndLine();
+            });
+
+        if ($enclosingMethod) {
+            $this->phpdoc->appendTag(Tag::createInstance(
+                '@see \\' . $enclosingClass->getName() . '::' . $enclosingMethod->getName() . '()'
+            ));
+        }
+    }
+
     /**
      * @param \ReflectionFunctionAbstract $method
      * @param \ReflectionClass $class