keysymdef.h: Improve doc & keysyms comments
Follow-up of the discussion in: xorg/lib/libx11!224.
This MR clarifies how to document deprecated keysyms and fixes a few comments.
PS: these are the only fixes required by the new keysym header file parser , also discussed in MR hereinabove.
@whot @benno