diff --git a/lib/Core/SourceCodeLocator/TemporarySourceLocator.php b/lib/Core/SourceCodeLocator/TemporarySourceLocator.php
index <HASH>..<HASH> 100644
--- a/lib/Core/SourceCodeLocator/TemporarySourceLocator.php
+++ b/lib/Core/SourceCodeLocator/TemporarySourceLocator.php
@@ -8,6 +8,27 @@ use Phpactor\WorseReflection\Core\SourceCodeLocator;
 use Phpactor\WorseReflection\Core\Exception\SourceNotFound;
 use Phpactor\WorseReflection\Core\Reflector\SourceCodeReflector;
 
+/**
+ * Source locator for keeping track of source code provided at call time.
+ *
+ * Note this locator IS NOT SUITABLE FOR LONG RUNNING PROCESSES due to the way
+ * it handles source code without a path.
+ *
+ * During a given process many calls maybe made to the reflector, and any code
+ * provided directory (rather than located from the filesystem) should have
+ * precedence over other code.
+ *
+ * Because it's possible to provide source without a path (which is a mistake)
+ * we have no way of identifying code which is _updated_ so we just push to an
+ * array with a numerical index in this case.
+ *
+ * In a long-running process (i.e. a server) this will result in an every
+ * growing stack of outdated data.
+ *
+ * This locator should ONLY be used on short-lived processes (i.e. web request,
+ * or RPC request) or in situations where you are confident you provide the
+ * path for all source code.
+ */
 class TemporarySourceLocator implements SourceCodeLocator
 {
     /**
Add note about the suitability of the temporary source locator