System.Formats.Cbor: Backport MS Docs documentation to triple slash

[carlossanlop]

We are working on a new documentation process plan, in which the main objective is to make triple slash comments the source of truth for documentation, instead of MS Docs: We want developers/maintainers to have an easier time maintaining the documentation for their APIs.

You can use the DocsPortingTool to automate the backport process: Run the tool targeting the assembly, then submit a PR with the changes.

You can find detailed instructions for the backporting process here.

Area owners are free to decide if they want to address this in 6.0 or in Future.

[ghost]

Tagging subscribers to this area: @eiriktsarpalis, @bartonjs
See info in area-owners.md if you want to be subscribed.

Issue Details

---

We are working on a new documentation process plan, in which the main objective is to make triple slash comments the source of truth for documentation, instead of MS Docs: We want developers/maintainers to have an easier time maintaining the documentation for their APIs.

You can use the DocsPortingTool to automate the backport process: Run the tool targeting the assembly, then submit a PR with the changes.

You can find detailed instructions for the backporting process here.

Area owners are free to decide if they want to address this in 6.0 or in Future.

Author:	carlossanlop
Assignees:	-
Labels:	area-System.Formats.Cbor, documentation
Milestone:	-

[eiriktsarpalis]

FWIW all CBOR documentation has been authored via triple-slash comments and automatically ported to dotnet-api-docs. We'd probably still need to backport to account for any changes that have been made on dotnet-api-docs only.

[eiriktsarpalis]

I tried running the backporting tool for CBOR and got the following errors:

$ DocsPortingTool -Direction ToTripleSlash -CsProj runtime/src/libraries/System.Formats.Cbor/src/System.Formats.Cbor.csproj -Docs dotnet-api-docs/xml/ -IncludedAssemblies System.Formats.Cbor -IncludedNamespaces System.Formats.Cbor -Save true
Verifying CLI arguments...
Specified Docs xml locations:
  -  dotnet-api-docs/xml/
Included assemblies:
 - System.Formats.Cbor
Included namespaces:
 - System.Formats.Cbor
Save:
 - True
Looking for Docs xml files...
Type 'T:System.Formats.Cbor.CborConformanceMode' added with 4 member(s) included: C:\Users\eirik\devel\dotnet\dotnet-api-docs\xml\System.Formats.Cbor\CborConformanceMode.xml
Type 'T:System.Formats.Cbor.CborContentException' added with 3 member(s) included: C:\Users\eirik\devel\dotnet\dotnet-api-docs\xml\System.Formats.Cbor\CborContentException.xml
Type 'T:System.Formats.Cbor.CborReader' added with 40 member(s) included: C:\Users\eirik\devel\dotnet\dotnet-api-docs\xml\System.Formats.Cbor\CborReader.xml
Type 'T:System.Formats.Cbor.CborReaderState' added with 21 member(s) included: C:\Users\eirik\devel\dotnet\dotnet-api-docs\xml\System.Formats.Cbor\CborReaderState.xml
Type 'T:System.Formats.Cbor.CborSimpleValue' added with 4 member(s) included: C:\Users\eirik\devel\dotnet\dotnet-api-docs\xml\System.Formats.Cbor\CborSimpleValue.xml
Type 'T:System.Formats.Cbor.CborTag' added with 16 member(s) included: C:\Users\eirik\devel\dotnet\dotnet-api-docs\xml\System.Formats.Cbor\CborTag.xml
Type 'T:System.Formats.Cbor.CborWriter' added with 41 member(s) included: C:\Users\eirik\devel\dotnet\dotnet-api-docs\xml\System.Formats.Cbor\CborWriter.xml
Finished looking for Docs xml files.

Reading source code projects...
Created a workspace for 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Opened the project 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Obtained the compilation for 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Type symbol 'System.Formats.Cbor.CborConformanceMode' not found in compilation for 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Type symbol 'System.Formats.Cbor.CborContentException' not found in compilation for 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Type symbol 'System.Formats.Cbor.CborReader' not found in compilation for 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Type symbol 'System.Formats.Cbor.CborReaderState' not found in compilation for 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Type symbol 'System.Formats.Cbor.CborSimpleValue' not found in compilation for 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Type symbol 'System.Formats.Cbor.CborTag' not found in compilation for 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Type symbol 'System.Formats.Cbor.CborWriter' not found in compilation for 'C:\Users\eirik\devel\dotnet\runtime\src\libraries\System.Formats.Cbor\src\System.Formats.Cbor.csproj'.
Porting comments from Docs to triple slash...

This is after running both Debug and Release builds in dotnet/runtime. Could you take a look?

[carlossanlop]

Known issue: dotnet/api-docs-sync#36 and we just merged a fix: dotnet/api-docs-sync#40

Can you please update the tool to the latest bits and re-run it?

BTW, the -Save true agument is not necessary. I have updated the tutorials to remove it.