为什么 PHPDoc 中的点会截断其余的描述？

Question

我正在尝试编写 PHPDoc 描述，当我输入一个点 (.) 时，它就会在代码助手中删除其余的描述。例如，

/**
 * A boolean value indicating whether code assitant worked with dots in PHPDoc.
 * As you can see, it did not work!
 * @var bool
 */
public $var = false;

我在代码助手中只看到第一行。我该如何解决这个问题？

Answer 1

Ashnazg 几乎是对的。通常有“简短摘要”。之后没有空行，因此它假设整个块（包括标签）属于摘要，并在第一个句号后被删除（因为它是一个简短摘要;)）

简短摘要之后和标签之前的换行符应该有效。

/**
 * A boolean value indicating whether code assitant worked with dots in PHPDoc.
 *
 * Should work ;)
 *
 * @var bool
 */
public $var = false;

Answer 2

我发现如果在句号后面放置 HTML 编码的空格字符（“ ”），则可以显示多个句子。例如：

/**
 * Sentence One. Sentence Two.
 */

但是，如果您想在 PHPDoc 注释中包含换行符以便更容易阅读源代码，则最多只允许三行。如果包含更多内容，则仅显示第一行。这是完全有道理的，因为您永远不需要超过三行。例如：

/**
 * Line one. 
 * Line two.  Another line two sentence. 
 * Line three. 
 * This fourth line being here will prevent lines 2, 3, and 4, from being displayed.
 */

感谢您提出这个问题。我一直想知道是不是我安装的PDE错误或者什么的。

Answer 3

我在 Eclipse (Helios) 中使用简短描述和长描述时没有任何运气 - 尽管它应该受到支持。

如果您想增加简短描述的长度，可以选择使用
标签。只要您的简短描述中不包含句点，就可以将其跨多行。如果您愿意，您甚至可以使用其他标签来添加项目符号列表。

/**
 * Function to take a 10 digit phone number and<br>
 * return it in North American standard format of:<br>
 * <ul><li>(123) 456-7890</li></ul>
 * 
 * @param int $phone <ul><li>up to 10 digit int for the phone number</li></ul>
 * @return string <ul><li>formatted phone number</li></ul>
 */

Eclipse Helios 支持此网页上列出的大多数（如果不是全部）DocBlock 格式标签。
phpDocumentor 教程：DocBlock 描述详细信息

但是，并非所有这些标签都适用于所有情况，并且本页其他部分中肯定有一些示例不起作用。但使用这些技术绝对可以让你的 phpDoc 块看起来更好。

Answer 4

代码助手逻辑很可能期望文档块描述存在于“一句话摘要描述，后面是更长的详细描述”，并且很可能只在弹出窗口中显示摘要描述。在 Eclipse 中，您可以通过 Tab 键进入代码助手弹出窗口，其中的信息会展开以显示所有内容（通过滚动条）。

更新：
在 Helios 上的 Eclipse PDT 中测试 KingCrunch 的精确布局（对句点的简短描述、空白、带/不带句点的附加描述、空行、标签）表明，第一句中的句点确实阻止了弹出窗口显示任何超出期限的描述。我什至将第二部分移到与第一部分相同的行上，并且超出句点的所有内容仍然没有出现。将其更改为逗号，然后将显示下一个句点之前的所有内容。好吧，除非逗号行和下一行之间有一个空行...在这种情况下，空行与句点具有相同的效果，阻止其后的所有内容。我认为无论描述片段是否可见，标签的查看和解释都没有问题。

因此，我相信 Eclipse 确实忽略了它遇到的第一个句点和/或空行之外的所有描述。我不知道有什么方法可以禁用这种行为。