XML documentation updates

[louthy]

One of the most idiotic things Microsoft ever did was to use XML as a 'comment' documentation-format when the language it is documenting is full of <, >, and & characters. I'd love to know who it was that thought this was a good idea.

They should be shunned forever!

Anyway, more seriously, I have ignored the 'well formed' XML documentation warnings, forever. I did so because I consider the readability of comments in code to be the most important factor. So, if I needed a < or a > and it looked OK in the source, then that was good enough for me.

I even built my own documentation generator that understood these characters and knew how to ignore them if the weren't known tags (something Microsoft should have done by now!)

I refused to make something like Either<L, R> turn into Either<L, R>

Anyway, there are places where this is problematic:

• Inline documentation tooltips in IDEs
• The new 'formatted' documentation of Rider (maybe VS too, but I haven't used it in ages).

The thing is, I still think the source-code is the most important place for readability, so requests like this I ignored until I could think of a better solution. Now I have a better solution which is to use alternative unicode characters that are close enough to <, >, and &, that they read naturally in source and in documentation, but are also not XML delimiters:

Original	Replacement	Unicode	Example (before)	Example (after)
<	〈	U+3008	Either<Error, A>	Either〈Error, A〉
>	〉	U+3009	Either<Error, A>	Either〈Error, A〉
&	＆	U+FF06	x && y	x ＆＆ y

The spacing isn't perfect and in certain situations they look a touch funky, but still legible, so I'm happy to go with this as it makes the documentation work everywhere without compromise. It's slightly more effort for me, but I'd rather do this than compromise the inline comments.

Over 120 source files have been updated with the new characters. There are now no XML documentation errors (and I've removed the NoWarn that suppressed XML documentation errors).

There may well be other unicode characters that are better, but at least now it's a simple search & replace if I ever decided to change them.

---

This discussion was created from the release XML documentation updates.