dotnet / dotnet/api-docs-sync

Docs Porting Tool improvement

Offen
#104 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
epic
Vorherrschende Sprache
C#
Sterne
14
Forks
21
PR-Merge-Kennzahlen
Keine gemergten PRs in 30 T.

Beschreibung

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:

- [x] 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: https://github.com/dotnet/api-docs-sync/pull/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: https://github.com/dotnet/api-docs-sync/pull/97

## P1

Only tackle this after we fix the P0s:

- [x] ToDocs: tests into actual unit tests, instead of feature tests. First PR addressing this: https://github.com/dotnet/api-docs-sync/pull/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 `` 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 `` 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 `
` 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: https://github.com/dotnet/api-docs-sync/pull/75
- [x] ~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.

Beitragsleitfaden

Für dieses Repository ist kein Beitragsleitfaden indexiert

Bewertung

Dieses Issue wurde noch nicht bewertet.

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.