2

Previously my understanding was that the purpose of the @version tag was to show to library users in which release a particular file was last changed. For example, if there is a new release for liblibrary v1.7, and its developers maintain @version tags in sources in actual state (either manually or with an automated tool), then one could look at the sources artifact and see whether that particular file has changed since previous version 1.6.

But here is a piece of documentation for javadoc, which says that @version tag in each source file should merely hold the current release version of the whole artifact.

From javadoc - The Java API Documentation Generator:

This tag is intended to hold the current version number of the software that this code is part of

But I don't see any usefulness in that at all. Why would anyone have the current release in each source file if you can see it in your build tool (before the artifact is built) or in the name of the artifact (after the artifact is built)?

So can you specify exactly what should be in the @version tag: the version when that file had last changed (so every file in a source artfiact potentially has its own @version tag), or just the version of the artifact (so every source file has the same @version tag)? Is the former approach actually ever used?

gvlasov
  • 18,638
  • 21
  • 74
  • 110
  • Related / duplicate: [javadoc: @version and @since](http://stackoverflow.com/questions/578363/javadoc-version-and-since). – Mick Mnemonic Jul 28 '15 at 23:31
  • @MickMnemonic I've seen that post and it doesn't answer my question. The accepted answer says: "The \@version tag should be the current version of the release or file in question. The %I%, %G% syntax are macros that the source control software would replace with the current version of the file and the date when the file is checked out." It doesn't specify what exactly is "the current version of the file", it might be one of both options I described. – gvlasov Jul 28 '15 at 23:36
  • I really need this question answered. : ( Sadly, all the sources are ambiguous. \*\*reads a spell to summon @JonSkeet \*\* – gvlasov Jul 31 '15 at 22:07
  • In the codebases I've worked with, `@version` has always meant the version of the source file, not the version of the software/artifact. When using a version control system, in my opinion, the tag is redundant, because the only reasonable way to keep its values updated is by auto-filling them by the VCS upon commit (so that the value matches the revision of the file). – Mick Mnemonic Jul 31 '15 at 22:22
  • @MickMnemonic Thanks for the input! But what if there was a Maven plugin that would get versions of particular files from VCS and insert the version of a file at placeholders near `@version` tag, so every time a project is built for release every file has a relevant `@version` tag in the distributable sources artifact? Would that be the way `@version` tag was meant to be used? – gvlasov Jul 31 '15 at 22:38

1 Answers1

2

In my experience, the version tag has always contained the current version of the file.

Since annotations can be checked at run-time, it can be useful/practical to check the version annotation on a file. An example could be to update a file from a network location (think video-game update).

Since the annotations are more directly useful to the program/compiler than the programmer, the version tag should always contain the current version.

However, each developer may use these version tags differently, and that is up to them. In the case you presented, they found that using the version tag in an unintended manner helps them in some way.

So yes, you can put whatever you'd like into the version tag. Whether or not it's useful is to be determined by your program.

As for your last question, yes. Version numbering varies wildly from one developer to another (I use the term developer in the context of a company/group, not individual). Some developers use a single version number for each stable release. Others use individual file version numbers.

I prefer the latter because it allows you to see how often certain files are updated or changed.

This is all conjecture and opinion of course.