What are some common pitfalls to avoid when using PHPDoc in PHP projects?

One common pitfall to avoid when using PHPDoc in PHP projects is not properly documenting all parameters and return types of functions. This can lead to confusion for other developers trying to use your code. To solve this, make sure to include detailed descriptions of each parameter and the expected return type in your PHPDoc comments.

/**
 * Calculate the sum of two numbers.
 *
 * @param int $num1 The first number.
 * @param int $num2 The second number.
 * @return int The sum of the two numbers.
 */
function calculateSum($num1, $num2) {
    return $num1 + $num2;
}