Removal of all javadoc @author tags - any objections?

Cervator

Project Lead and Community Wizard
Contributor
Design
Logistics
SpecOps
#1
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
#2
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
#3
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

Project Lead and Community Wizard
Contributor
Design
Logistics
SpecOps
#4
@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
#5
OK with me Cervator ...... "......Make it so, #1 ......" ..... sorry my mind regresses to fond memories on TV :coffee:
 

manu3d

Pixel Forge Artisan
Contributor
Architecture
#6
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
#7
hi, I am also for the removal of the author tag. Espeically without email address it has as good as no use.
 

Cervator

Project Lead and Community Wizard
Contributor
Design
Logistics
SpecOps
#10