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

【问题标题】：What does @internal actually mean and how to use it?@internal 实际上是什么意思以及如何使用它？
【发布时间】：2016-02-01 05:12:18
【问题描述】：

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

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

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

我的问题：

我对@987654327@ 的理解是否正确？如果不是，正确的用法是什么？
如果我的理解是正确，为什么 PhpStorm 删除我的 @internal 函数，暗示它们不应该被使用？如何正确使用标记为 @internal 的函数？

【问题讨论】：

这是他们文档中的一个例子：manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/… 你理解正确，但是我不确定为什么 PhpStorm 会删除它，除非它的格式不正确。
只是因为这个原因才把它划掉：告诉你这个方法/字段/类/等不应该在类之外使用。我相信 ATM 它使用样式来表示“已弃用”的样式。事情是——这只是基本支持——票尚未关闭——欢迎您关注它以获取进度通知：youtrack.jetbrains.com/issue/WI-22284
感谢您提供的信息和指向 PhpStorm 问题的链接！我很高兴我的理解很清楚，这只是 PhpStorm 支持的一个问题让我感到困惑。

【解决方案1】：

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

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

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

【讨论】：

【解决方案2】：

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

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

【讨论】：

【解决方案3】：

对某些人来说可能是微不足道的，但要注意的是，如果可能，将函数声明为私有可能比使用 @internal 更好。

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

【讨论】：