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

Question

非常简单的问题--在编写docblocks时，我应该如何确定我是否应该说一个结构元素和另一个元素，以及应该在什么时候告诉人们@uses @see另一个元素？

我做了一些谷歌搜索，没有多少运气，我能看到的唯一区别是@uses有一个匹配的@used-by标签，而@see是单向的。这是不是意味着@uses/@used-by比@see更受欢迎呢？

干杯。

Answer 1

当我想突出显示下面的方法使用由@uses标记标识的方法/属性时，我选择@uses。我使用@uses的主要原因是创建双向的@uses--@used-by链接。始终谨慎地放置@used将最终意味着我可以查看文档中的方法/属性，并在其上看到@used-by标记的列表，从而一目了然地知道这个方法/属性可以产生多广泛的影响。这在准备重构全局变量时特别有用，因为全局变量的用法隐藏在方法代码中。

我使用@see来表明对于下面的方法，存在一些有趣的理由来看一下@see点在哪里。如果有一个类属性被这个方法和@see方法操纵，特别是以某种相似/相关的方式，我可能会在这两个方法上都放上@see标签，甚至可能给那个属性加上一个@use。

TL;DR？我使用@uses只是为了说明该方法实际上利用了@uses目标。我会使用@see作为其他任何“你也应该知道这件事”的理由。