woocommerce.php PHPDoc cleanup: correct @returns and @deprecated markup

Having @deprecated helps detecting them at the code level rather than waiting for _deprecated_function() to happen.