Docs Porting Tool improvement

[carlossanlop]

There are several improvements we need to address to stabilize this tool for usage in all dotnet repos in an automated fashion.

P0

Before tackling anything else, we need to solve the following:

• Separate the two directions into two separate processes. This will help ensure we keep concerns separate and simplify maintenance and future improvements.
• Add classes that wrap the dotnet-api-docs xml types and members, but only return xml objects. This will simplify working with Roslyn APIs.
  • Use the code in this branch as insipration: Merge carlossanlop/main with jeffhandley/retain-directives #99 so that the Roslyn code consumes the new xml-returning classes.
• Understand and fix the issue causing the tool to not be able to load Roslyn projects every time we bump dependencies. Use the code in this branch as inspiration: Bump dependencies to try to fix TripleSlash unit test failures #97

P1

Only tackle this after we fix the P0s:

• ToDocs: tests into actual unit tests, instead of feature tests. First PR addressing this: PortToDocs: Add methods that either collect files automatically, or allow passing documents manually #110
• ToTripleSlash: move all remarks to their own xml files next to the source code, and point to the file in the triple slash xml <remarks> item.
  • Convert the dotnet-api-docs markdown to normal xml if possible.
• ToTripleSlash: Figure out how to detect examples in remarks efficiently, move them to their own xml files next to the source code, and point to the file in the triple slash <example> item.
• Detect multi-platform documents (*.Unix.cs, *.Windows.cs, etc.) and move their documentation to a single xml file next to the source code, then point to that file in all the triple slash xml items.
• ToDocs: Port the -or- lines in exceptions correctly, to ensure they have enough endlines so they render correctly in MS Docs.
• ToTripleSlash: backport -or- lines in exceptions with <br/> or other features to ensure they get wrapped and save space.
• ToTripleSlash: Add the ability to wrap lines to 120 characters (or a custom number), as requested by WinForms.

P2

• Save logs to file. There used to be a change that used System.Threading.Channels, but it was causing some messages to get lost, or not print well so it was backed-out. We can reuse its code but fix the issues: Speed up execution by offloading logging #75
• Move the code from this tool into a forked arcade repo and adapt the two executables to be consumable by arcade. We already moved this tool to its own repo under dotnet.

[carlossanlop]

@jeffhandley @RussKie please feel free to edit the list with more tasks.

[RussKie]

P2

• Move the code from this tool into a forked arcade repo and adapt the two executables to be consumable by arcade.

This depends on the outcomes of the next week's meeting with @markwilkie. But if this tool is decided to be a part of Arcade, this will be the next priority because it will lay the foundation for other work.