Вы правы в том, что @version может использоваться несколько раз в проекте. Тег преднамеренно гибкий и может использоваться от одной крайности (версии всего пакета, поэтому все теги показывают одно и то же значение) до другой крайности (каждый отдельный класс / метод / функция / любой другой имеет свою собственную версию # и изменение history, поэтому класс v1.2.3 может иметь десять методов, каждый из которых показывает свои собственные номера версий). В целом, однако, я не думаю, что когда-либо видел случай, когда версия использовалась более детально, чем на уровне «устанавливаемой библиотеки / пакета / приложения».
Что касается тега @since ... в каком бы стиле вы не использовали тег @version для данного элемента, тег @since представляет версию #, в которой элемент был впервые представлен. В этом случае вы можете использовать тег @since как журнал изменений, и, таким образом, у вас будет несколько тегов @since для одного и того же элемента (см. Пример функции dump() здесь - http://docs.phpdoc.org/references/phpdoc/tags/since.html).
Мое предложение о том, как использовать эти теги:
- «версия» - это полная версия выпуска пакета / библиотеки / приложения, обозначенная как находящаяся в одном репозитории управления версиями.
- Я бы поместил теги @version только в докблоки на уровне файлов, докллоки на уровне классов и в докллоки автономных функций
- Я бы использовал теги @since только для API-уровня классов и методов
Было бы легко чрезмерно использовать эти теги и, следовательно, сделать поддержание значений тегов кошмарным.