Opened 13 years ago
Closed 13 years ago
#14921 closed defect (bug) (wontfix)
WP_Dependencies is tagged as external but is core package
| Reported by: |
|
Owned by: | |
|---|---|---|---|
| Milestone: | Priority: | normal | |
| Severity: | normal | Version: | 3.0 |
| Component: | Inline Docs | Keywords: | |
| Focuses: | Cc: |
Description
While creating some runtime and static analyzer tools I ran over a problem rating files properly as core-files with the following files:
- wp-includes/class.wp-dependencies.php
- wp-includes/class.wp-scripts.php
- wp-includes/class.wp-styles.php
- wp-includes/functions.wp-scripts.php
- wp-includes/functions.wp-styles.php
Those files are tagged as being package "BackPress". I suggest to remove this external constraint. The foremost reason is this code has been contributed to and is developed in WordPress core, so it's not an external but a core file.
Core files are tagged as package "WordPress" in the project.
The current @package value mislabels them as being external files (BackPress backports WordPress and other projects' code into a library of it's own).
As new subpackage value I suggest "Dependencies". Additionally the @since tagging of those files / classes / functions can be improved.
Most of the code has been contributed in 7011.diff by mdawaffe.
The current tagging has been contributed in 7550.r8991.2.diff and committed in [9002] (Related: #7550).
Attachments (2)
Change History (9)
#2
follow-up:
↓ 3
@
13 years ago
These were extracted out of WordPress core and are now considered external packages as part of the BackPress library. Despite the fact that we maintain it, I find @package fine here.
At most, I would suggest:
@since BackPress r74 @since WordPress 2.6.0
#3
in reply to:
↑ 2
@
13 years ago
- Component changed from General to Inline Docs
Replying to nacin:
These were extracted out of WordPress core and are now considered external packages as part of the BackPress library. Despite the fact that we maintain it, I find @package fine here.
I can not consider files with wordpress core code that are still maintained in wordpress (and not BackPress) as external packages. And I doubt that there is such a consideration. That would turn the principles of Upstream upside-down.
BackPress is very closely to WordPress core, but that does not mean that it normally re-labels wordpress package files in WordPress.
I'm even quite sure that this misalignment in these five files has been done in error. There are other files that are in BackPress library and in WordPress as well which do not @package this way. It are just those five files that are out of the row. For no special need btw.
At most, I would suggest:
@since BackPress r74 @since WordPress 2.6.0
This can create problems with PHPdocs. @since by design contains the version of @package (manual):
Use @since to document revisions, as in "This function has been a part of this package since version 2.0"
Next to that, it mixes responsibilities. The BackPress project itself needs to keep track for the various -Press (bbPress, GlotPress) sister projects. That's nothing we can and should do in the wordpress project.
Generally spoken: If it's an external, it should be treated as an external. If it's not it's not.
Considerations that make some files external by PHPDocs while factually being plain WordPress code is underminig PHPDocs and is reducing and even hindering its use.
@since concrete as in wordpress