phpstorm - @internal 实际上是什么意思以及如何使用它？

Question

@internal 是什么意思标签在 PHPDocs 中使用时的含义以及它是如何工作的？我已阅读 the documentation对于这个标签，并得到了这个定义。

The @internal tag is used to denote that associated Structural Elements are elements internal to this application or library. It may also be used inside a long description to insert a piece of text that is only applicable for the developers of this software.

我明白了它的要点，但我不明白我将如何在项目中实际使用它？我已阅读示例，我的理解是标记为 @internal 的函数意味着它被用作软件的一部分，而不是被外部的东西使用。例如，在 PHP 库中，如果函数被标记为 @internal它不是库提供的公共(public) API 的一部分。

我的问题:

是我对@internal的理解吗？正确的？如果不是，正确的用法是什么？

如果我的理解是正确的，为什么 PhpStorm 会删除我的 @internal暗示它们不打算使用的功能？如何正确使用标记为 @internal 的函数?

Answer 1

这是 PhpStorm bug .它不应该罢工@internal库/包内部使用的方法。

所以是的，您对 @internal 含义的理解标签是正确的 - 它用于将公共(public)/ protected 方法标记为不属于公共(public) API 的一部分。您应该忽略这些在库内使用的警告。

从技术上讲，即使对于 3rd 方库，也没有什么可以阻止您使用此类方法，但您应该注意后果 - 它们没有向后兼容性 promise ，因此它们可以在没有任何警告的情况下更改、重命名或完全消失。