为什么 PHPDoc 中的点删除了其余的描述？答案

【问题标题】：Why dots in PHPDoc cut the rest of the description?为什么 PHPDoc 中的点删除了其余的描述？
【发布时间】：2010-12-06 12:23:26
【问题描述】：

我正在尝试编写 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;

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

【问题讨论】：

“删减”描述的其余部分是什么意思？你看它是代码还是看不到它？
代码助手不完整显示描述。
也许它只显示了第一行？

标签： php eclipse phpdoc

【解决方案1】：

我在 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 Tutorial: DocBlock Description Details

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

【讨论】：

【解决方案2】：

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

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

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

【讨论】：

你可以在 Eclipse 中看到完整的描述吗？这就是我想要看到的！我试图集中描述框，它仍然不会显示任何内容。我正在使用 Eclipse PDT。

【解决方案3】：

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

简短摘要之后和标签之前的换行符应该可以工作。

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

【讨论】：

你认为我可以使用 PDT 在 Eclipse 中看到完整的摘要吗？

【解决方案4】：

我发现如果您在句点后放置一个 HTML 编码的空格字符（“&nbsp;”），您可以显示多个句子。例如：

/**
 * Sentence One.&nbsp;Sentence Two.
 */

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

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

感谢您发布此问题。我一直在想我是否安装了错误的 PDE 或什么的。

【讨论】：