DocBlocks: Difference between @uses and @see

Question

Fairly straightforward question - when writing docblocks, how should I determine whether I should be saying a structural element @uses another, and when should it tell people to @see the other element?

I've done a bit of Googling and a bit of SO searching without much luck, and the only difference I can see is that @uses has a matching @used-by tag, whereas @see is one-way. Does this mean that @uses/@used-by are preferred to @see or is there more to it?

Cheers.

Answer 1

I choose @uses when I want to highlight that the method below makes use of the method/property identified by the @uses tag. My key reason for using @uses at all, though, is to create that two-way @uses--@used-by linkage. Being conscientious about placing @uses consistently will ultimately mean that I can look at a method/property in my docs and see a list of @used-by tags on it, thereby knowing at a glance how widespread this one method/property can have effects. This is particularly useful when preparing to refactor away global variables whose usage is hidden down in a method's code.

I use @see to indicate that for the method below, there exists some interesting reason to also take a glance at where @see points. If there is a class property that is manipulated by this method and the @see method, particularly in some similar / related way, I might put @see tags on both methods, and maybe even a @uses to that property.

TL;DR? I'd use @uses only to show that the method actually utilizes the @uses target. I'd use @see for any other "you should be aware of this other thing too" reason.