Duplicate Annotations in Core Files

[Sdfendor]

While updating our shop to the most recent version and then again in PR #2577 we noticed, that in core files the category and package annotations are duplicated, first in the license docblock and then after that in the class docblock. Isn't that redundant? Couldn't one occurrence be removed?
I'm asking this questions instead of already working on a PR because we noticed that those duplicates aren't only accidentally present in existing files but are actively added in PRs e.g. the one mentioned above. Maybe there is reason for this duplication that I'm not aware of.

example:

[fballiano]

I don't know why we have body category and package, probably category is meant to be in a project where there are both openmage and other softwares?

[fballiano]

ah ok, you mean the 2 blocks, I didn't consider them duplicate since the first one is more or less the general copyright for the file, while the second one is relative to the class.

it is true that we'll never have more than a class per file, but that's the reason i think

[Sdfendor]

I don't see this eventuality happen in the foreseeable future, maybe never to be honest. The autoloader works on a class per file basis after all. One would have to work around some problems to support multiple classes per file. It's not a big problem or anything to have those duplicate annotations, but I'm not a big fan of redundancy where there is no need for it.

[fballiano]

it will never happen for sure, i was just trying to understand why it was done that way since the beginning of time

[Sdfendor]

Additionally I got the idea to ask because the last update touched all the files about the "do not change this file to receive updates"-disclaimer. That meant for me there is "no tabu" to change those parts that are present - as you say - since the beginning of time.

[fballiano]

there's no tabu, the only thing we have to respect is the copyright part.

i didn't remove any of those docblocks because i thought the reason they existed is the one i was saying before, that's all

[addison74]

Good observation.

From the first comment block I would keep the @copyright and @license that I would move to the second comment block.

On the @author line I would remove the email address or change it to a valid one.

On the @license line I would add the email address [email protected] (if it is functional).

The new order should be:

@category
@package
@author
@copyright
@license

[fballiano]

If you want I’ve some preg_replace ready for that

[sreichel]

Please wait with this. Its possible that phpdoc/... use this in some way. I'd no time to test ...

[justinbeaty]

Personally I think it may be better to do in a separate PR. If we merge it into #2295 then it will make it harder to verify that commit via the git diff command I posted over there.

But I am okay either way, and I can easily rebase @2295 if needed.

[sreichel]

Separate PR means we touch nearly every file again :(

My idea was ... if you already have a script for contributors, lets extend it :)

[justinbeaty]

Separate PR means we touch nearly every file again :(

My idea was ... if you already have a script for contributors, lets extend it :)

We already did touch all the files in #2297 as well as #2562, #2558, etc, so we are already past doing it all in just one commit.

The update-copyright.php script wouldn't be the best place to do that, since this is a one-and-done task. But in any case, let's wait to make sure phpdoc isn't using this at all.

[sreichel]

My PR just added docblocks in the same way they are used all over openmage - to group classes in phpdocumentor correctly.

I did not test, but having package in both blocks seems not required ... but ... why???

[Sdfendor]

Was just a quick example I had saved in the clipboard, nothing especially "bad" with the PR, not at all. I didn't want to suggest anything like that. I simply noticed the duplication and wanted to know why it is present in the whole core alltogether and whether there is a reason for the duplication besides "it was always like that".

[sreichel]

wanted to know why it is present in the whole core alltogether and whether there is a reason for the duplication besides "it was always like that".

Yes, it is present all over core. There are only a few files without 2nd docblock.

Reasons ... not sure about this, but first block belongs to the file itself (copyright, disclaimer ...) and second belongs to the class (package, methods, ...)

Not sure if we have to touch this.

[fballiano]

exactly what I thought

[Sdfendor]

I'm totally fine with the two docblocks, but I didn't understand the duplicate:

I can follow the possible explanation by @fballiano but still I would have thought as you said:
first block => file => copyright, license,
second block => class =>category, package, maybe author