I like to make use of the fact that names can be documented in multiple places.
In the header file, I write a brief description of the method, and document all its parameters – these are less likely to change than the implementation of the method itself, and if they do, then the function prototype needs to be changed in any case.
I put long-format documentation in the source files next to the actual implementation, so the details can be changed as the method evolves.
For example:
mymodule.h
/// @brief This method adds two integers.
/// @param a First integer to add.
/// @param b Second integer to add.
/// @return The sum of both parameters.
int add(int a, int b);
mymodule.cpp
/// This method uses a little-known variant of integer addition known as
/// Sophocles' Scissors. It optimises the function's performance on many
/// platforms that we may or may not choose to target in the future.
/// @TODO make sure I implemented the algorithm correctly with some unit tests.
int add(int a, int b) {
return b + a;
}