Description: ------------ It would be really nice if a new @usedby tag were introduced. This would make the docblocks more meaningful when users read the source code.

@usedby is for @uses, i.e. put a @uses tag in, and @usedby will be auto-inserted in the documentation of the package that is using it

Yes, I saw that in the documentation. The reason for this request is to make it easier for developers reading the source code and writing the docblocks. While reading the source code, it's often not apparent that a method/file/etc is used by something else. A @usedby tag would make it crystal clear. Also, while writing the docblocks, it's easier to just throw a @usedby tag where you are now than to go open up a separate file somewhere and put in the @uses there. Let alone, the element where the @uses should go may not even have a docblock.

use @see and describe in the description portion of the field that it is used by the thing

Putting in a @see is a workaround because it does not automatically produce the nice link back from the other element (how putting "@uses B" automatically makes a link in B that says "@usedby A". Plus, in the event A has "@uses B" while B has a "@see A", element B's output will have two pointers to A: "@see A" and "@usedby A".

Generally speaking, I think you'll be reading code that USES some class/method that is defined elsewhere, so that if you're overly curious about "what does this class/method REALLY do right here in the middle of my file", you benefit from the USES tag right here... it helps you jump to the original class. On the other hand, if you're looking at the class/method definition code itself, you're not really concerned with how many thousand other procedural files are happily utilizing your class/method. The more you reuse your class in other files, the more you'd clutter up your class file with USEDBY tags right here in your source code. The generated documents seem like a better place for such accumulated clutter, so that it doesn't distract you from reading your actual class code. I can see your point about "coder's flexibility" to put a USES or USEDBY pointer on either end of the point-path, but I imagine the complexity around parsing the both of them and resolving any duplicate pointers to each other would be ugly and painful. Feels kind of like deciding whether or not to install a dozen gas tank lids on your car... it would make it easier on you when deciding how to park by the gas pump, but is the extra flexibility worth the cost? If this linking method were indeed highly useful theoretically, I'd say that both hyperlinking and database foreign keys would have evolved this way too.

again, tag bloat is to be avoided. @usedby is an auto-generated tag, I don't want to introduce ambiguity unless absolutely necessary, and in this case, if you want a 1-way reference, use a @see If you're looking for clarity in the source code, use this // also used by XXX::XXX No need to pollute the phpDocumentor space to accomplish something that has nothing to do with the generated output

> if you want a 1-way reference, use a @see I'm proposing a two-way tag. > has nothing to do with the generated output I'm proposing that @usedby produce output in both the element it's in and a reciprocal @uses tag in the element referred to.