See inline documentation standards

Note: This tag has been used in the past, but should no longer be used.

What gives?

I am building a plugin to build a codex from the source of a plugin/theme and i think the @uses tag would be perfect for linking functions to hooks and hooks to functions.

  • Don't see a good reason for it. Personally I just ignore some suggestions made by the WP core developer team. In short: I use @uses and will continue to do so. Last but not least, it is your plug-in, not core code, so use @uses as you want I say.
    – Nicolai
    Mar 24 '15 at 15:17
  • Totally agree with @ialocin And to be really really honest, Wordpress coding standards are a mess. Even the core developers don't adhere to it. @uses is valid and not depreciated in any way in doc blocks Mar 24 '15 at 15:22
  • 1
    Which standards? I have seen really bad plugins on wordpress.org which totally does not stick to any kind of standard. The person who wrote that piece of garbage in the documentation should explain WHY we cannot use @uses. I'm busy with a huge pagination plugin based on PSR-4 standards. I want to see that been declined from the respitory on wordpress.org. Mar 24 '15 at 15:42
  • 2
    There is no official documentation that I know of which gives any type of reason why @uses should not be used. Just to on standards, Wordpress supposedly uses PEAR coding standards, now in that same page you are referring to in your question, there is this line Only when the new – external – PSR-5 recommendations are finalized, will across-the-board changes be considered, such as deprecating certain tags. Want to talk about standards :-) Mar 24 '15 at 16:02
  • 1
    @uses is practically useless, because every parser for find usages is more accurate = never out of sync.
    – fuxia
    Mar 24 '15 at 20:36

I'm not 100% sure but I guess it's because usage of @uses can be covered with @see

From phpDocumentor docs

@uses is very similar to @see, see the documentation for @see for details on format and structure. The @uses tag differs from @see in two ways. @see is a one-way link, meaning the documentation containing a @see tag contains a link to other documentation. The @uses tag automatically creates a virtual @usedby tag in the other documentation that links to the documentation containing the @uses tag. In other words, it is exactly like @see, except a return link is added automatically.

The other difference is that @uses only accepts one element to link to, and a description of that element.

Probably, WP people decided that it isn't worth to have 2 tags so similar but only maintain one.

BTW, @uses is a fine tag. If you want to support it just do it and document its support in documentation.

  • " except a return link is added automatically." This is why i want to use it, because this is what i want to use it for. I want to use this feature to be able to scan any plugin, so i would want to stick to what devs will be using. If only i could get them to remove that line from their docs. Mar 24 '15 at 16:15
  • 2
    So, as said, use it. PS, do you know the existence of github.com/rmccue/WP-Parser ?
    – gmazzap
    Mar 24 '15 at 16:19
  • 1
    +1 But, they are actually not that similar, right? Thats rhetorical of course. And to treat them as equal, as the documentation standard does, is just utterly stupid. @StiofanO'Connor Really, just use it and don't care.
    – Nicolai
    Mar 24 '15 at 16:37
  • 1
    If only i could get them to remove that line from their docs That is like farting against a tornado. Don't drive yourself mad over something you cannot change. Until there is no official documentation which documents the depreciation of @uses, you must use it as you wish. @StiofanO'Connor Mar 24 '15 at 16:52

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.