I know we have questions about comments in general but I'm specifically wondering about Java Doc style method documentation here.
I've been pruning unnecessary comments as I refactor and I've noticed our code has painfully obvious descriptions of methods.
/** * @name save * @desc Validates and saves submitted daily plant production information. */
Most of the "documented" functions are just method names used by convention in our MVC framework (CakePHP). It's inherently obvious that the save method in the Production Controller performs the necessary actions to save Production Information.
We don't actually use Java Doc and I question the value of these descriptions even if they were included in Java Doc style documentation. The only reason I haven't touched these because they're method documentation that's supposed to be valuable. The method documentation also hasn't been used consistently, about half of our Controller/model methods are documented.
Is there any reason to keep these obvious "Java Doc" comments or should I prune them in favor of "self documenting code" and only make Java Doc comments for less obvious methods?