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

class-resolver/src/class_resolver/base.py

Lines 142 to 147 in 403da7a

	def register(
	self,
	element: X,
	synonyms: Optional[Iterable[str]] = None,
	raise_on_conflict: bool = True,
	):

, but that's also no so obvious