Remove all @package and @subpackage tags from function DocBlocks

[DrewAPicture]

As has been ​pointed out by duck_, Rarst, and others, @package and @subpackage tags not found in file-header-level doc blocks can cause those and other functions/classes to be skipped by the parser. This is expected behavior in regard to the phpDoc spec.

The proposal is to remove all @package/@subpackage PHPDoc tags that fall below the file header level of any given file. This of course would exclude of the numerous external libraries bundled with core.

[Rarst]

Note that it is _valid_ for class (top level class phpdoc). It's only invalid for functions (and methods I assume since that doesn't make sense). Of course if file header has package already repeating it in class is just redundant.

I have compiled a list of core files with more than one @package match in them: ​https://gist.github.com/Rarst/9206962

[DrewAPicture]

Replying to Rarst:

Note that it is _valid_ for class (top level class phpdoc). It's only invalid for functions (and methods I assume since that doesn't make sense). Of course if file header has package already repeating it in class is just redundant.

I talked to @kpdesign about this yesterday and we both agree the better option would be to only have package tags in the file headers, i.e. once per file.

The consensus was to promote a clean, simple standard instead of "package tags go in the file header except in (this), (this), or (this) instance. If we just stick with only using package tags in file headers I think it will create far less confusion going forward.

[Rarst]

I managed to overlook the patch. :) I am not against removing them from classes, just noted that it's valid contrary to the original ticket description. Since that is already done in patch and decided on - works perfectly. :)

[GaryJ]

Replying to Rarst:

Of course if file header has package already repeating it in class is just redundant.

As noted in (draft) PSR-5, and seen in general documentation generators, the @package tag is NOT inherited by classes from the file-level DocBlocks. Functions inherit it, but not classes, so @package is still needed on class DocBlocks, even if the class is the only thing in a file (as it should be) and the file has a matching @package tag as well.

[Rarst]

A little more generic question is if @package WordPress even doing anything anyone needs?

From PSR-5

If, across the board, both logical and functional subdivisions are equal is it NOT RECOMMENDED to use the @package tag, to prevent maintenance overhead.

There are no real subdivisions or namespaces in WP, neither there are may "packages" (couple bundled libs do come with them) and @package WordPress is applied rather randomly and purposelessly.

I think on more general level possible actions are either standardizing and enforcing how it's used or getting rid of it altogether.

[GaryJ]

Just as those bundled libs come with them because the libs can be used in a wider system, so should WordPress. If WP is used in a wider system (making up only a part of a website or online presence), then parsing the whole system will neatly mark out what is WP, what is Magento, and what is something else. It's playing nicely with others, and it's the right thing to do, even if WP has no sub packages and everything is @package WordPress.

There shouldn't be the ambiguity of looking at a file from WP, and having to assume it's a WordPress file rather than a lib, because there's no @package tag.

The other thing is for file identification - should a file be found and read out of context (i.e. outside of a WP-only site, by someone who doesn't know WP), then having a file-level DocBlock at the top (fairly consistent for each and every file) with a @package tag instantly identifies where that file has come from.

Let's not get distracted from the ticket - that function-level @package and @subpackage tags are wrong, and should be removed regardless of follow-ups related to the use of @package throughout WP.

[DrewAPicture]

Keep class-level package tags

[DrewAPicture]

27200.2.diff​ retains file- and class-level @package and @subpackage tags.

[DrewAPicture]

In 27262:

Remove all @package and @subpackage PHPDoc tags not at the file- or class-levels in core.

See #27200.

[markjaquith]

DrewAPicture — anything else needed on this ticket?

[DrewAPicture]

Replying to markjaquith:

DrewAPicture — anything else needed on this ticket?

Nope we're good.