The coding standards state to use @see for “Reference to a function, method, or class that is heavily-relied on within.”
Ok. But if I have a function, it always means that something uses it, because there’s no need to write a function if it is not used. And what does “heavily-relied” mean? It means if I’ll remove a function, the dependent function won’t work correctly? Still every function, and still I should always use “@see” tag.
If I look at WP or WC code, “@see” tag is used somehow randomly.
I really don’t get it. Please, explain. When should I use “@see” tag?
“@see” tag is used somehow randomly
No wonder as any documentation in the end depends on the programmer’s decision of what is worthy of being documented and how.
Documentation in general should not be a verbal description of the code unless the code is extremely non trivial, but add a human friendly summery of what the code does and why. Therefor it is trivial that functions used in the code are not worthy to be referenced in @see as they are already in the code. You should use it when there is some dependence on how a different function works, either because you get input from it in one form or another, or it is going to process your output (very relaxed definitions of input and output here).
So it is down to a judgment call. Will you be able to understand why function A does without knowing anything about function B? If so, the @see is not needed, but if for example A sets a global variable to be used by B, probably both should contain a reference to each other (obviously good code should just not have such things 😉 ).
