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

Question

@internal在PHPDocs中使用时标记的含义是什么？它是如何工作的？我已阅读此标记的文档并获得此定义.

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

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

我的问题:

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

Answer 1

这是 PhpStorm错误。它不应该攻击@internal在库/包内部使用的方法。

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

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