Document the synonyms mechanism (in particular, normalizing underscores)

[cmungall]

We use the synonym mechanism in OAK and many other projects, the docs for this are a bit buried.

Also there appears to be magic that happens that can cause hard to debug errors; e.g.

my_parser_resolver.synonyms.update(
   "my_name": ActualParser,
   ...

Invalid Parser name: my_name Valid choices are: ['my_name']

What seems to be happening is undocumented normalization removing all underscores

[cthoyt]

I see, I never thought of this before. You might be able to use https://github.com/cthoyt/class-resolver/blob/403da7a0dd54e7174d533894887de7723cc9a6b6/src/class_resolver/base.py#L142-L147, but that's also no so obvious