Improve XML comment indenting

[JeremyKuhne]

This commit updates XML comments and documentation to indent per standard. It relies on an AI generated Python script to generate the original changes, then it was manually reviewed and modified. Overall, these modifications aim to enhance maintainability and understanding of the code for developers.

The script generation

This is an interesting example in trying to get a terrible first result to something that was much more usable. The script could be improved further. Ignoring CDATA sections would have helped a bit, for example.

Microsoft Reviewers: Open in CodeFlow

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 61.28784%. Comparing base (eaaf38c) to head (58f7098).
Report is 2 commits behind head on main.

Additional details and impacted files

@@                 Coverage Diff                 @@
##                main      #13095         +/-   ##
===================================================
+ Coverage   61.28341%   61.28784%   +0.00442%     
===================================================
  Files           1541        1541                 
  Lines         158281      158281                 
  Branches       14743       14743                 
===================================================
+ Hits           97000       97007          +7     
+ Misses         60584       60577          -7     
  Partials         697         697                 

Flag	Coverage Δ
Debug	61.28784% <ø> (+0.00442%)	⬆️
integration	10.73772% <ø> (ø)
production	39.15743% <ø> (+0.00726%)	⬆️
test	95.67280% <ø> (ø)
unit	36.58010% <ø> (+0.00726%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[KlausLoeffelmann]

FWIW, it makes way more sense in those cases to have AI generate a Roslyn Analyzer/CodeFix, which would take care of this, so we can have it in the repo permanently and ready to use for everyone?

I think this would be more sustainable, because it would not only be useful in one single batch operation, but also directly as a new Editor functionality AND it would then also detect issues for us, and not only patch them.

I'll be out next week, but we can discuss approach ideas the week after, if you'd like!

[JeremyKuhne]

FWIW, it makes way more sense in those cases to have AI generate a Roslyn Analyzer/CodeFix, which would take care of this, so we can have it in the repo permanently and ready to use for everyone?

I think this would be more sustainable, because it would not only be useful in one single batch operation, but also directly as a new Editor functionality AND it would then also detect issues for us, and not only patch them.

I'll be out next week, but we can discuss approach ideas the week after, if you'd like!

@KlausLoeffelmann Trying to do that as well, but it is way harder. The rules are way more complicated than it might seem at first and (additionally) the AI tools aren't particularly adept at writing Roslyn analyzers from what I've experienced. The analyzer has to be 99.99%+ accurate if we want to make it a breaking rule at our repo's scale. Writing a clean-up script can be done at a much lower bar with no upkeep costs.

This PR is an important step, as part of the problem comes from replicating existing comments that aren't up to snuff. Making progress in small, but significant, and agile steps.

[Tanya-Solyanik]

Oops

[JeremyKuhne]

Yeah, we shouldn't have these comments anyway. I caught most of them, but missed this one.

[Tanya-Solyanik]

Please remove long lines full of slashes in the next PR. I'm ok to merge this as is unless Klaus finds anything critical

[KlausLoeffelmann]

I don't know.
It touches 240 files in one go.

Maybe we should scope it smaller but then try to be more ambitious, aiming for more gain (see below).

If then with a bolder attempt (which, if it was agentic, could of course go really south😄) only a smaller scope would be affected, we could easier detect that in a review, if we'd let it do corner cases automatically as we would have done them also.

And then we could increasingly add additional scopes or even increase the scope(s) in size. That would then also include things like, amending comments where comments are now missing, correcting typos, correcting grammar, check for parameter completeness and such. There are 10s of additional ideas which come to mind, which would then just be about adding to the prompt(s).

But...just my 2 cents!

[KlausLoeffelmann]

Well, to be honest, I wasn't done reviewing yet.
I would have rather discussed this, and be giving a bit more time.

Also, I do NOT at all agree with you with this. In fact I would flat out say, that the opposite is the case, and I can gladly put together a small video, which show respective approaches. Because I have DONE that several times.

...the AI tools aren't particularly adept at writing Roslyn analyzers from what I've experienced.

But obviously, we would just also need some time to compare expectation and results.

I would very much like to ask you for the next times for a bit more time for me to review before merging a change which touches 240 files.

@merriemcgaw FYI.

[JeremyKuhne]

I would very much like to ask you for the next times for a bit more time for me to review before merging a change which touches 240 files.

It wasn't intentional, it was set to auto merge. Tonya approved, it went in.

Also, I do NOT at all agree with you with this. In fact I would flat out say, that the opposite is the case, and I can gladly put together a small video, which show respective approaches. Because I have DONE that several times.

Bottom line: this was fast (way less than an hour) and gets us in better shape. 99% better is fine for moving things forward. It doesn't preclude doing more involved things. The worst thing that comes out of this is I might have made a few comments worse. We've done much worse in prior sweeps. Luckily for us, we have source control. We can fix individual cases, or undo the whole thing was a mistake.