I have been reading up on phpDoc and code comments.
Am I right in my understanding that the @version can be used multiple times in a project.
The documentation in the link above suggests so with the statement "The @version tag can be used to indicate the current version of Structural Elements."
So for example in a plugin, the main plugin itself could be version 1.0.0, but then a class of that plugin could be version 3.0.0. If so does the @since relate directly to the previous @version tag used?
You are correct in "the @version can be used multiple times in a project". The tag is deliberately flexible, and can be used from one extreme (the version of the overall package, so all tags show the same value) to the other extreme (every single class/method/function/whatever has its own version# and change history, so a class at v1.2.3 could have ten methods all showing their own different version numbers). In general, however, I don't believe I've ever seen a case where the version was used any more granularly than at the "installable library/package/application level".
Regarding the @since tag... in whatever style you use the @version tag for a given element, the @since tag represents the version# that the element was first introduced. A variation on this is where you use the @since tag like a changelog, and thus you have multiple @since tags on the same element (see the dump() function example here -- http://docs.phpdoc.org/references/phpdoc/tags/since.html).
My suggestion in how to use these tags: - the 'version' is the overall release version of a package/library/application as denoted by all of it being in one version control repository - I would only put @version tags in file-level docblocks, class-level docblocks, and standalone function docblocks - I would only use @since tags on API-level classes and methods
It would be easy to overuse these tags, and thus make maintenance of the values of the tags a nightmare.