Use of the @subpackage tag in documentation

[henry.wright]

The documentation standards ​mention that the @subpackage tag should be used in all file header DocBlocks but the phpDocumentor docs consider the tag deprecated. See ​here.

Should I continue to use @subpackage when documenting plugins?

[DrewAPicture]

Hi Henry,

I would encourage you to use or not use @subpackage tags at your discretion.

Part of the issue we have in core is that our parser currently only supports phpDocumentor 1.0 in which name-spaced @package tags are not supported and @subpackage tags are not deprecated. Thus the note in the WordPress documentation standards.

When we opted to write our standard, we heavily leaned toward historical precedence of the code base, and that's something that we've maintained through today. The benefit of approaching change in this way is that later, when the PSR-5 recommendations are finalized and approved, it will be that much simpler for us to adjust to those new recommendations.

[henry.wright]

Thanks for the clarification, much appreciated.