Skip to content

Remove package phpdoc annotation#781

Merged
mblaney merged 1 commit intosimplepie:masterfrom
jtojnar:phpdoc-redundant-package
Jan 31, 2023
Merged

Remove package phpdoc annotation#781
mblaney merged 1 commit intosimplepie:masterfrom
jtojnar:phpdoc-redundant-package

Conversation

@jtojnar
Copy link
Member

@jtojnar jtojnar commented Jan 30, 2023

@subpackage is deprecated and @package is mostly redundant with PHP namespaces.

And while the annotations sometimes do not match the namespaces perfectly, which could be taken as a separate logical structure, having two separate hierarchies is IMO more confusing than helpful. Especially when the annotations are not even picked up by ApiGen.

https://docs.phpdoc.org/2.9/references/phpdoc/tags/package.html
https://docs.phpdoc.org/2.9/references/phpdoc/tags/subpackage.html
ApiGen/ApiGen#1081

Removed with the following commands:

sd '(?m)(?:\n^[ \t]+\*)?\n[ \t]+\*[ \t]+@package.+?(?:\n[ \t]+\*[ \t]+@subpackage.+)?(\n[ \t]+\*/|(\n[ \t]*\*))' '$2$1' "$(rg -l @subpackage -t php)"

Fixes: #780

@Art4
Copy link
Contributor

Art4 commented Jan 30, 2023 •
edited
Loading

If ApiGen shows the namespaces, then the "packages" are not needed. I have 3 notes/questions:

  1. there is another @package in build/header.txt that could be removed.

  2. While we are on the phpdoc topic I wonder how the {@see ...} syntax works. E.g. see https://github.com/simplepie/simplepie/blob/1.8.0/src/SimplePie.php#L1411-L1432

    But ApiGen seems to ignore the syntax and shows it in plain text: http://simplepie.ogion.cz/api/SimplePie.SimplePie/#_set_output_encoding

    How should this normally works? Can we fix this in this PR?

  3. Can we fix the copyright year in all files? There are places where the year is 2004-2016 or 2004-2022.

@jtojnar
Remove package phpdoc annotation
4672473 
`@subpackage` is deprecated and `@package` is mostly redundant with PHP namespaces.

And while the annotations sometimes do not match the namespaces perfectly,
which could be taken as a separate logical structure,
having two separate hierarchies is IMO more confusing than helpful.
Especially when the annotations are not even picked up by ApiGen.

https://docs.phpdoc.org/2.9/references/phpdoc/tags/package.html
https://docs.phpdoc.org/2.9/references/phpdoc/tags/subpackage.html
ApiGen/ApiGen#1081

Removed with the following commands:

    sd '(?m)(?:\n^[ \t]+\*)?\n[ \t]+\*[ \t]+@Package.+?(?:\n[ \t]+\*[ \t]+@subpackage.+)?(\n[ \t]+\*/|(\n[ \t]*\*))' '$2$1' "$(rg -l @subpackage -t php)"
@jtojnar jtojnar force-pushed the phpdoc-redundant-package branch from 737ee1b to 4672473 Compare January 30, 2023 19:46
@jtojnar
Copy link
Member Author

jtojnar commented Jan 30, 2023

  1. While we are on the phpdoc topic I wonder how the {@see ...} syntax works. E.g. see 1.8.0/src/SimplePie.php#L1411-L1432

It worked in older ApiGen versions, newer ones expect Markdown in PHPDoc descriptions.

  1. Can we fix the copyright year in all files? There are places where the year is 2004-2016 or 2004-2022.

I would rather handle that with #778.

  1. there is another @package in build/header.txt that could be removed.

Removed.

@mblaney mblaney merged commit 7fba7db into simplepie:master Jan 31, 2023
@Art4 Art4 mentioned this pull request Jan 31, 2023
Merged
@jtojnar jtojnar deleted the phpdoc-redundant-package branch March 17, 2023 21:13
@Art4 Art4 added this to the 1.9.0 milestone Sep 30, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Art4 Art4 Art4 approved these changes

Assignees

No one assigned

Labels

size/L

Projects

None yet

Milestone

1.9.0

Development

Successfully merging this pull request may close these issues.

[ENH] Revise the phpdoc tags @package and @subpackage

3 participants

@jtojnar @Art4 @mblaney