Removal of all javadoc @author tags - any objections?

Discussion in 'Announcements' started by Cervator, Mar 29, 2015.

  1. Cervator

    Cervator Project Lead and Community Wizard Staff Member

    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: Mar 30, 2015
  2. socram8888

    socram8888 Member

    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)
  3. msteiger

    msteiger Active Member

    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.
  4. Cervator

    Cervator Project Lead and Community Wizard Staff Member

    @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
  5. metouto

    metouto Active Member

    OK with me Cervator ...... "......Make it so, #1 ......" ..... sorry my mind regresses to fond memories on TV :coffee:
    • Funny Funny x 1
  6. manu3d

    manu3d Pixel Forge Artisan

    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.
  7. Florian

    Florian Active Member

    hi, I am also for the removal of the author tag. Espeically without email address it has as good as no use.
  8. Immortius

    Immortius Lead Software Architect Staff Member

    Let them burn.
  9. Linus

    Linus Member

    I have no objections to removal.
  10. Cervator

    Cervator Project Lead and Community Wizard Staff Member

Share This Page