Improve generated description from xml docs

[kiapanahi]

Addresses: #1428

This PR uses a compiled regex to find and replace all namespaced types/methods/properties in a summary section in components' XML docs.

Microsoft Reviewers: Open in CodeFlow

[drewnoakes]

I have only a comment on the implementation. I'll leave it to others to comment on the general direction of this change.

[sebastienros]

Would it be simpler if the logic was integrated in StripXmlElements directly by checking for well-known tags (<see cref, <see langword) and falling back to a default logic (taking the first argument). This way you can "just" check to the colon and then skip the first two chars.
It would not need any Regex and the false positives that @drewnoakes mentioned.

[kiapanahi]

Would it be simpler if the logic was integrated in StripXmlElements directly by checking for well-known tags (<see cref, <see langword) and falling back to a default logic (taking the first argument). This way you can "just" check to the colon and then skip the first two chars. It would not need any Regex and the false positives that @drewnoakes mentioned.

The latest commit addresses those missing regex issues @drewnoakes mentioned. However, going down the path of changing the StripXmlElements() method and checking against known tags and attributes would AFAIK result in having the text of an attribute that might not always contain their full names. For example:

KeyVaultSecretIdentifier instead of Azure.Security.KeyVault.Secrets.KeyVaultSecretIdentifier.

Or did I misunderstand you?

[sebastienros]

My comment was about not using a Regex at all. Trying to find these occurrences could be prone to errors if the content doesn't match for any reason we can't think of right now. Instead, just process the value when we detect it in StripXmlElements, so the line that take the first attribute in the tags will instead format the value and return it. That will remove the need for a Regex, and it will also let us return custom formatted values ('{0}', "{0}", links, ...) to the documentation if we want instead of applying a generic '{0}'.

[kiapanahi]

My comment was about not using a Regex at all. Trying to find these occurrences could be prone to errors if the content doesn't match for any reason we can't think of right now. Instead, just process the value when we detect it in StripXmlElements, so the line that take the first attribute in the tags will instead format the value and return it. That will remove the need for a Regex, and it will also let us return custom formatted values ('{0}', "{0}", links, ...) to the documentation if we want instead of applying a generic '{0}'.

Sorry for the delay.
After a few hours of fiddling around, I added a simple(-ish) implementation of your suggestion; essentially moving all the "formatting" logic into StripXmlElements method altogether.