[clang][NFC] Add some documentation about the use of NamedDecl::getDeclName in diagnostics.

As explained in eb10b065, sending a NamedDecl*
in a diagnostic should generally be preferred over sending the DeclarationName
from getDeclName(). Let's document that.