Removal of all javadoc @author tags - any objections?

Cervator

Org Co-Founder & Project Lead
Contributor
Design
Logistics
SpecOps
This has been a topic on and off for some time. @author tags in Javadoc are not very useful, are often copy pasted and inaccurate, and really don't add anything Git history doesn't.

With Java 8 javadoc generation gets more strict and @msteiger put a big PR up that fixes the errors. Part of the errors relate to email formatting in @author tags, which have been very inconsistent at best. The current fix is simply removing the emails. Instead I wonder if we just remove the tags entirely.

Apparently the Apache license frowns upon the @author tag too. Lots of cons, few to no pros.

I figure some devs might feel nice seeing your author tag in there, so I wanted to ask if anybody would object if we remove them.

Will give it a couple days and try to ping the big @Contributor team here and on GitHub for added notifications. Group mentions used to work here, unsure if that was lost in the last upgrade

Edit: Nope, no group mention worky, oh well. We do have a Javadoc page in the GitHub wiki I forgot to include at first: https://github.com/MovingBlocks/Terasology/wiki/JavaDoc

Edit2: I figure removing javadoc author tags doesn't clash with attribution in Apache 2.0 ? That's about the copyright header ("MovingBlocks") alone?
 
Last edited:

socram8888

Member
Contributor
I'm cool with the idea as long as the vast majority of them are removed (I don't want my name to be the only removed from the sources :D)
 

msteiger

Active Member
Contributor
World
Architecture
Logistics
The Apache Software Foundations itself has a issued a policy the remove author tags in all ASF software projects. (http://www.theinquirer.net/inquirer/news/1037207/apache-enforces-the-removal-of-author-tags)
Similarly, gradleware removed them from the gradle source code (https://github.com/gradle/gradle/commit/a1b9612fa06f90f20b115cede557e22287501034).
TerasologyLauncher even has a CheckStyle settings that flags author tags with a warning.

Whatever is decided here, I suggest dealing with the JavaDoc fixes separately. These are separate issues and it would cause A LOT of merge conflicts if removing the author tags was done in parallel.
 

Cervator

Org Co-Founder & Project Lead
Contributor
Design
Logistics
SpecOps
@socram8888 - yeah the idea is all or nothing. Either all the tags go or none of them go (although we would still need to fix the emails in that case)

@msteiger - yup separate changes. I'll probably merge the initial PR tonight, but I wanted the excuse to ping the Contributor team on GitHub somewhere for extra notification fun :D
 

metouto

Active Member
Contributor
Art
OK with me Cervator ...... "......Make it so, #1 ......" ..... sorry my mind regresses to fond memories on TV :coffee:
 

manu3d

Active Member
Contributor
Architecture
I agree with the removal, as to me the @author tag doesn't make sense. As you say git provides far more information and perhaps one or more "@owner" tags might be more useful, if kept up to date. I am not much impacted by the change though. People like Begla, Immortius, Msteiger e Florian (to name a few) should have a bigger say on the matter as they are among the biggest contributors.
 

Florian

Active Member
Contributor
Architecture
hi, I am also for the removal of the author tag. Espeically without email address it has as good as no use.
 

Cervator

Org Co-Founder & Project Lead
Contributor
Design
Logistics
SpecOps
Top