From 2ff9672a49a81a2b9c79b9359294c0c7f0f5152d Mon Sep 17 00:00:00 2001
From: Richard van Baarsen <baarsen@pm.me>
Date: Fri, 11 Sep 2020 16:35:41 +0200
Subject: [PATCH] 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 <markus@fischer.name>
---
 CHANGELOG.md  |  1 +
 src/Macro.php | 21 +++++++++++++++++++++
 2 files changed, 22 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 96bd055..b77e3f8 100644
--- a/CHANGELOG.md
+++ b/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)
diff --git a/src/Macro.php b/src/Macro.php
index 55132fe..088557e 100644
--- a/src/Macro.php
+++ b/src/Macro.php
@@ -4,6 +4,7 @@ namespace Barryvdh\LaravelIdeHelper;
 
 use Barryvdh\Reflection\DocBlock;
 use Barryvdh\Reflection\DocBlock\Tag;
+use Illuminate\Support\Collection;
 
 class Macro extends Method
 {
@@ -33,6 +34,8 @@ class Macro extends 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 @@ class Macro extends 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