This quite possibly belongs in a different plugin, but some of the issues I've come across include...
Capitalisation of tags. eg.
# @Summary This class installs foo
#
Someone meant to use @summary but used @profile instead.
# @profile This profile installs foo
#
Using the name of a parameter as a tag instead of @param
# @ensure Whether to install or remove foo