DocBlocks: @uses和@see的区别



相当直接的问题-当编写docblock时,我应该如何确定我是否应该说一个结构元素@uses另一个,以及它应该何时告诉人们@see另一个元素?

我做了一点谷歌搜索和一点SO搜索没有太多的运气,我能看到的唯一区别是@uses有一个匹配的@used-by标签,而@see是单向的。这是否意味着@uses/@used-by@see更受欢迎?

欢呼。

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

我使用@see是为了表明对于下面的方法,有一些有趣的原因也可以看看@see指向哪里。如果有一个类属性是由这个方法和@see方法操作的,特别是以一些类似/相关的方式,我可能会在两个方法上都放上@see标签,甚至可能给那个属性加一个@uses。

TL,博士?我使用@uses只是为了显示该方法实际上利用了@uses目标。我用@see来表示"你也应该注意其他事情"。

相关内容

  • 没有找到相关文章

最新更新