PHPDoc Function Changelog (@change?)

Question

What is the best way to document changes in a function with PHPDoc? Something like

@change 2010.20.16  user  added feature x
@change 2010.20.26  user  added feature y

would be great. But assume there's no @change option... If i add it anyways, what will PHPDoc do with it? Or is there a better / more correct way to document function changes?

Answer 1

It might be better to just dump your SCM log into a changelog txt file then try to embed it into the source code.

Reasons why:

1. Staleness - It won't do anyone any good if you stop adding change notes which is likely to happen if having to go on a coding marathon/sprint of doom.

2. Unconventional - I can't remember seeing a project with that in depth of inline documentation. Sometimes conventions are flat out stupid, but I think the wisdom for this one is cutting down on maintenance.