@internal实际意味着什么以及如何使用它？

Question

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

  

@internal标记用于表示关联的结构元素是此应用程序或库的内部元素。它也可以在长描述中用于插入仅适用于该软件开发人员的文本。

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

我的问题：

• 我对@internal的理解是否正确？如果没有，那么正确的用法是什么？
• 如果我的理解 正确，为什么PhpStorm会删除我的@internal函数，暗示它们不打算被使用？我如何正确使用标记为@internal的函数？

Answer 1

这是PhpStorm bug。它不应该打击库/包中使用的@internal方法。

所以是的，您对@internal标记含义的理解是正确的 - 它是用于标记公共/受保护方法而不是公共API的一部分。您应该忽略这些警告以便在库中使用。

从技术上讲，即使对于第三方库，也没有任何东西可以阻止你使用这些方法，但你应该知道后果 - 它们没有向后兼容的承诺，因此它们可以被更改，重命名或完全消失而不会警告。

Answer 2

对某些人来说可能是微不足道的但是注意如果可能的话声明一个私有函数可能比使用Settings更好。

并不是说此标签没有有效用途，但如果您觉得需要使用它，那么检查您的设计总是一个不错的选择。

Answer 3

我相信这是程序员对某些特定用法的评论。 我标记了我的建议，在哪种情况下可以使用此功能或替代功能（例如“仅在CLI模式下使用此功能”或“仅在需要行数据时使用此功能。在所有其他情况下请考虑使用包装器”）

https://docs.phpdoc.org/references/phpdoc/tags/internal.html

@内部 @internal标记用于表示关联的结构元素是此应用程序或库的内部元素。也可以在长说明内使用它插入仅适用于该软件开发人员的文本。