WordPress.org

Make WordPress Core

Opened 7 years ago

Closed 7 years ago

#27200 closed defect (bug) (fixed)

Remove all @package and @subpackage tags from function DocBlocks

Reported by: DrewAPicture Owned by:
Milestone: 3.9 Priority: normal
Severity: normal Version:
Component: General Keywords: has-patch
Focuses: docs Cc:

Description

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.

Attachments (2)

27200.diff (62.0 KB) - added by DrewAPicture 7 years ago.
27200.2.diff (47.0 KB) - added by DrewAPicture 7 years ago.
Keep class-level package tags

Download all attachments as: .zip

Change History (13)

@DrewAPicture
7 years ago

#1 follow-ups: @Rarst
7 years ago

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.

Last edited 7 years ago by Rarst (previous) (diff)

#2 in reply to: ↑ 1 @DrewAPicture
7 years ago

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.

#3 @Rarst
7 years ago

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. :)

#4 in reply to: ↑ 1 @GaryJ
7 years ago

  • Summary changed from Remove all non-file-level @package/@subpackage tags to Remove all @package and @subpackage tags from function DocBlocks

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.

#5 @Rarst
7 years ago

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.

#6 @GaryJ
7 years ago

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
7 years ago

Keep class-level package tags

#7 @DrewAPicture
7 years ago

  • Milestone changed from Awaiting Review to 3.9

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

#8 @DrewAPicture
7 years ago

In 27262:

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

See #27200.

This ticket was mentioned in IRC in #wordpress-dev by svn-b42. View the logs.


7 years ago

#10 follow-up: @markjaquith
7 years ago

DrewAPicture — anything else needed on this ticket?

Last edited 7 years ago by markjaquith (previous) (diff)

#11 in reply to: ↑ 10 @DrewAPicture
7 years ago

  • Resolution set to fixed
  • Status changed from new to closed

Replying to markjaquith:

DrewAPicture — anything else needed on this ticket?

Nope we're good.

Note: See TracTickets for help on using tickets.