psalm-internal - document usage of @internal and @psalm-internal tags

docs/issues.md

@@ -367,7 +367,8 @@ echo (new A)->foo;
 
 ### InternalClass
 
-Emitted when attempting to access a class marked as internal an unrelated namespace or class.
+Emitted when attempting to access a class marked as internal an unrelated namespace or class, or attempting
+to access a class marked as psalm-internal to a different namespace.
 
 ```php
 namespace A {
@@ -388,7 +389,8 @@ namespace B {
 
 ### InternalMethod
 
-Emitted when attempting to access a method marked as internal an unrelated namespace or class.
+Emitted when attempting to access a method marked as internal an unrelated namespace or class, or attempting
+to access a method marked as psalm-internal to a different namespace.
 
 ```php
 namespace A {
@@ -411,7 +413,8 @@ namespace B {
 
 ### InternalProperty
 
-Emitted when attempting to access a property marked as internal from an unrelated namespace or class.
+Emitted when attempting to access a property marked as internal from an unrelated namespace or class, or attempting
+to access a property marked as psalm-internal to a different namespace.
 
 ```php
 namespace A {

docs/supported_annotations.md

@@ -19,6 +19,8 @@ Psalm uses the following PHPDoc tags to understand your code:
   Used to specify what properties can be written on object that uses `__set`
 - [`@deprecated`](https://docs.phpdoc.org/references/phpdoc/tags/deprecated.html)
   Used to mark functions, methods, classes and interfaces as being deprecated
+- [`@internal`](https://docs.phpdoc.org/references/phpdoc/tags/internal.html)
+   used to mark classes, functions and properties that are internal to an application or library.
 
 ### Off-label usage of the `@var` tag
 
@@ -235,6 +237,39 @@ $a = new A();
 $a->bar = 5; // this call fails
 ```
 
+### `@psalm-internal`
+
+Used to mark a class, property or function as internal to a given namespace. Psalm treats this slightly differently to
+the PHPDoc `@internal` tag. For `@internal`, an issue is raised if the calling code is in a namespace completly
+unrelated to the namespace of the calling code, i.e. not sharing the first element of the namespace.
+
+In contrast for `@psalm-internal`, the docbloc line must specify a namespace. An issue is raised of the calling code
+is not within the given namespace.
+
+```PHP
+namespace A\B {
+    /**
+    * @psalm-internal A\B
+    */
+    class Foo { }
+}
+
+namespace A\B\C {
+    class Bat {
+        public function batBat(): void {
+            $a = new \A\B\Foo();  // this is fine
+        }
+    }
+}
+
+namespace A\C {
+    class Bat {
+        public function batBat(): void {
+            $a = new \A\B\Foo();  // error
+        }
+    }
+}
+```
 ## Type Syntax
 
 Psalm supports PHPDoc’s [type syntax](https://docs.phpdoc.org/guides/types.html), and also the [proposed PHPDoc PSR type syntax](https://github.com/php-fig/fig-standards/blob/master/proposed/phpdoc.md#appendix-a-types).