What are some best practices for documenting PHP code, especially when targeting both programmers and non-programmers?

When documenting PHP code for both programmers and non-programmers, it's important to provide clear and concise explanations of the code's functionality, purpose, and usage. Use comments to explain complex logic or algorithms in simple terms, and include examples or use cases to illustrate how the code should be used. Additionally, consider using a documentation generator like PHPDocumentor to automatically generate documentation from your code comments.

/**
 * This function calculates the sum of two numbers and returns the result.
 *
 * @param int $num1 The first number to be added.
 * @param int $num2 The second number to be added.
 * @return int The sum of $num1 and $num2.
 */
function calculateSum($num1, $num2) {
    return $num1 + $num2;
}