Users have mentioned a few cases with the javadoc isn't clear.

For pointer types, the javadoc contains the original pointer type but we should check if that is the case everywhere, and we if we can do better.