Create @used-by tag

[toxalot]

According to the docs for @uses

Documentation generators SHOULD create a @Used-By tag in the documentation of the receiving element that links back to the element associated with the @uses tag.

[mvriel]

This issue needs to be researched; as far as I know this functionality should already be there

[toxalot]

Perhaps this is due to issues with the @uses tag. I'm testing with procedural code which is all in the global namespace. I've tried @uses function_name() and @uses \function_name(). Neither one links to function_name(). Since there is no link to, it may be understandable that their is no link from either.

I've seen this behavior with the clean template. I can't say how it would work with the responsive template because it doesn't show any tags for functions.

[mrclay]

Is there any reason @used-by isn't included in the navigation?

[mvriel]

@mrclay @used-by is a dynamically added tag on the destination element for an @uses tag. As there is no need to declare it yourself it isn't in the navigation

[mrclay]

Confirmed in latest .phar version, @uses does not add corresponding Used By declaration. https://gist.github.com/mrclay/d03e757ec63d0bffffd7

[mrclay]

@mvriel Are you suggesting that (once this bug is fixed) I can use @used-by directly and @used will be dynamically added to the consuming party?

[ashnazg]

@mrclay backwards from that... you would use @uses directly, thus that element's doc will show the @uses and its target... and, the output docs would then contain @Used-By in the target's doc.

[ashnazg]

The rationale here is that if method foo() internally uses method bar() that is defined somewhere else, it's easier to document it there at foo() with @uses bar() than to have to go to bar()'s docblock and put @used-by foo() there. Thus, simply by denoting via @uses right where the "remote thingy" got used, the doc for that thingy ends up with a list of all its usages around the codebase via a list of generated @used-bys.

[ashnazg]

Doing it this way also works out better with regard to keeping the list up to date, as the only thing to maintain is the @uses bar() there at foo()... it'll be easy to notice if you later remove the bar() call from in foo(), thus remove the tag.

I don't think I know anyone who would look at a list of @used-bys at bar() and make the effort to periodically go verify that bar() is still used by all those targets ;-)

[mrclay]

Moving my discussion to #1234