documentation - DocBlocks：@uses 和 @see 之间的区别

Question

相当直截了当的问题——在编写文档块时，我应该如何确定我是否应该说@uses另一个结构元素，以及何时应该告诉人们@see另一个元素？

我已经做了一些谷歌搜索和一些 SO 搜索，但运气不佳，我能看到的唯一区别是@uses有一个匹配的@used-by标签，而是@see单向的。这是否意味着@uses/@used-by是首选@see还是有更多？

干杯。

Answer 1

当我想强调下面的方法使用由@uses 标记标识的方法/属性时，我选择@uses。不过，我完全使用@uses 的关键原因是创建双向@uses--@used-by 链接。认真对待@uses 始终如一地放置最终意味着我可以查看我的文档中的方法/属性并查看其上的@used-by 标签列表，从而一目了然地知道这个方法/属性可以产生多大的影响. 这在准备重构其用法隐藏在方法代码中的全局变量时特别有用。

我使用@see 表示对于下面的方法，有一些有趣的理由也可以看一下@see 指向的位置。如果有一个由这个方法和@see 方法操作的类属性，特别是以某种类似/相关的方式，我可能会在这两个方法上加上@see 标签，甚至可能在那个属性上加上一个@uses。

TL；博士？我只使用@uses 来表明该方法实际上利用了@uses 目标。我会将@see 用于任何其他“您也应该注意其他事情”的原因。