Allow porting Docs comments to Triple Slash in source #23

carlossanlop · 2020-11-19T19:57:01Z

The Libraries team wants to make triple slash comments the source of truth to simplify the documentation efforts from developers. In order to get there, we first need to bring back all the documentation we have in MS Docs into source code.

This change adds new logic that allows copying documentation contents from dotnet-api-docs xml files back into the triple slash comments trivia section of public APIs in C# code, on an assembly by assembly basis.

This is the first successful attempt.

Pending:

Add unit tests.
Add documentation for new APIs.
Update the readme.

Future (nice to have):

Wrap existing triple slash comments information in a class, to simplify the process of overwriting. There may be some rare cases where the docs in dotnet-api-docs are empty (To be added.) but there is valid documentation in triple slash, and we want to make sure it gets preserved. It's rare since we have already manually ported our /// documentation to dotnet-api-docs in previous efforts.

carlossanlop · 2020-11-19T19:58:22Z

cc @pgovind @jeffhandley @safern in case you want to take a look.

safern · 2020-11-19T23:27:38Z

Libraries/ToTripleSlashPorter.cs

+                return;
+            }
+
+            Compilation? compilation = project.GetCompilationAsync().Result;


We still need to figure out how to get all compilations so that we get all the locations of an API for the cases where there is no an OS agnostic file for that API. Anyway, that could be done when we hit that scenario.

Libraries/RoslynTripleSlash/TripleSlashSyntaxRewriter.cs

…nstructor.

Add the Nuget.Frameworks package to the Tests project so that the underlying csproj consumes it without failure.

Support event, field and delegate.

Remove boilerplate message. Avoid adding ## Remarks. Fix bug preventing exception comments from being added.

Fix nullability warnings. Obtain all projects related to all relevant symbols.

…nstructor.

Add the Nuget.Frameworks package to the Tests project so that the underlying csproj consumes it without failure.

Support event, field and delegate.

Remove boilerplate message. Avoid adding ## Remarks. Fix bug preventing exception comments from being added.

Fix nullability warnings. Obtain all projects related to all relevant symbols.

…structor. Avoid adding CDATA to remarks.

Convert langwords.

…ug when detecting that string.

… converted to see crefs. Detect primitive types in see crefs and convert them to their simplified representation. Add unit tests to verify this.

…ocsPortingTool into TripleSlashRoslyn

…ecution.

carlossanlop · 2021-01-29T16:42:17Z

This PR is covering enough cases that I think I can merge it. I added a GitHub CI action to run the unit tests and they are passing now.

Pending tasks for the next PR:

We still need to figure out how to get all compilations so that we get all the locations of an API for the cases where there is no an OS agnostic file for that API. Anyway, that could be done when we hit that scenario.
Use Roslyn API to tell if a token is a reserved keyword. There are a bunch of static APIs there to tell you facts about the tokens.
Automatically add the <GenerateDocumentationFile> set to true in the csproj after porting docs. Use the info provided in the email with the Roslyn team.
Investigate how to manually run a roslyn analyzer in the source code. For example, IDE0001 needs to be executed very often after porting comments, to remove unnecessary name qualification if its namespace is already being imported among the using directives.
Maybe compile the assembly after the port, to determine if there are any errors warnings to address, right then and there.
Make sure the tool is generic enough so it can be used not only in the runtime repo, but also in WPF/WinForms/etc.
Update the readme file in this repo.
Add documentation for the new APIs in this tool.
Nice to have: Wrap triple slash comments in a class. It would simplify and make conversion even more clear.

carlossanlop added 9 commits November 19, 2020 11:41

Move locations

a0aa93f

Docs changes.

eb5c1c6

IntelliSense XML rename and changes.

318a78a

Triple Slash rewriter.

5a04476

Shared code changes.

a15ef72

DocsPortingTool changes.

14cd186

Solution file.

e4476c9

install as tool update.

1bcb3a6

Unit tests.

1588ea6

carlossanlop mentioned this pull request Nov 19, 2020

Libraries APIs are fully documented using efficient workflows dotnet/runtime#44969

Open

16 tasks

safern reviewed Nov 19, 2020

View reviewed changes

carlossanlop commented Nov 19, 2020

View reviewed changes

Libraries/RoslynTripleSlash/TripleSlashSyntaxRewriter.cs Outdated Show resolved Hide resolved

carlossanlop commented Nov 19, 2020

View reviewed changes

Libraries/RoslynTripleSlash/TripleSlashSyntaxRewriter.cs Outdated Show resolved Hide resolved

carlossanlop commented Nov 19, 2020

View reviewed changes

Libraries/RoslynTripleSlash/TripleSlashSyntaxRewriter.cs Outdated Show resolved Hide resolved

carlossanlop added 12 commits November 20, 2020 17:33

Cleanup.

f821775

Newline fine tuning.

ec2b4b4

Move existing unit test code to PortToDocs folder.

5241e52

Move MSBuild registering code into its own method and call it from co…

d511989

…nstructor.

Add tests for docs to triple slash porting.

d101c51

Ensure exceptions are thrown in unit tests when registering MSBuild.

f1faa1a

Add the Nuget.Frameworks package to the Tests project so that the underlying csproj consumes it without failure.

Remove log message that exits, instead throw on error.

8d39db3

Fix minor errors in test files.

a3e6e1f

Fix assembly and namespace naming in test code.

3c88fed

Fine tuning detection of some elements.

97de4f3

Support altmember, related and seealso.

31ef6ca

Support event, field and delegate.

Fix some more exceptions vs errors.

f5e1713

Remove boilerplate message. Avoid adding ## Remarks. Fix bug preventing exception comments from being added.

carlossanlop force-pushed the TripleSlashRoslyn branch from 25c8711 to f5e1713 Compare January 7, 2021 23:52

carlossanlop mentioned this pull request Jan 8, 2021

Backport docs for System.IO.Compression.Brotli dotnet/runtime#46716

Merged

Make some simplifications on remarks based on feedback.

c66b551

Fix nullability warnings. Obtain all projects related to all relevant symbols.

carlossanlop added 25 commits January 28, 2021 11:41

Move MSBuild registering code into its own method and call it from co…

43e29bd

…nstructor.

Add tests for docs to triple slash porting.

c0b9343

Ensure exceptions are thrown in unit tests when registering MSBuild.

f3689af

Add the Nuget.Frameworks package to the Tests project so that the underlying csproj consumes it without failure.

Remove log message that exits, instead throw on error.

ce021d8

Fix minor errors in test files.

9537939

Fix assembly and namespace naming in test code.

5861c1d

Fine tuning detection of some elements.

7f6c6b1

Support altmember, related and seealso.

8469636

Support event, field and delegate.

Fix some more exceptions vs errors.

7a21a47

Remove boilerplate message. Avoid adding ## Remarks. Fix bug preventing exception comments from being added.

Make some simplifications on remarks based on feedback.

f9c8532

Fix nullability warnings. Obtain all projects related to all relevant symbols.

Fix calling the VSInstance loading code before calling the porter con…

9c7fc6e

…structor. Avoid adding CDATA to remarks.

Address test PR suggestions.

701ef44

Ignore extra info in xrefs when converting to crefs.

83d02a6

Convert langwords.

Added missing test for displayProperty which uncovered an unhandled b…

05c749f

…ug when detecting that string.

Advanced DocId detection in remarks, excluding prefixes that can't be…

ea1bb2b

… converted to see crefs. Detect primitive types in see crefs and convert them to their simplified representation. Add unit tests to verify this.

Merge branch 'TripleSlashRoslyn' of https://github.com/carlossanlop/D…

9da11f5

…ocsPortingTool into TripleSlashRoslyn

Add more asserts messages to check files and dirs exist in CI test ex…

d2e5f98

…ecution.

Print more details when error in line comparison in ToDocsTests

fba6668

Add BasePortTests with output helper

36448aa

Move back line compare to the end

93d13fd

Print expected and actual extra lines before asserting

0d6b933

More lines

ff64860

bug

cdc8fb1

Append interface remark lines one by one

e7e3c03

Newlines in docs

220216f

carlossanlop mentioned this pull request Jan 28, 2021

Ability to reference a method group in XML comment dotnet/csharplang#320

Closed

Simplify primitive type replacement.

0bd418f

carlossanlop merged commit 5794617 into master Jan 29, 2021

carlossanlop deleted the TripleSlashRoslyn branch January 29, 2021 16:44

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Allow porting Docs comments to Triple Slash in source #23

Allow porting Docs comments to Triple Slash in source #23

carlossanlop commented Nov 19, 2020

carlossanlop commented Nov 19, 2020

safern Nov 19, 2020

carlossanlop commented Jan 29, 2021 •

edited

Loading

Allow porting Docs comments to Triple Slash in source #23

Allow porting Docs comments to Triple Slash in source #23

Conversation

carlossanlop commented Nov 19, 2020

carlossanlop commented Nov 19, 2020

safern Nov 19, 2020

Choose a reason for hiding this comment

carlossanlop commented Jan 29, 2021 • edited Loading

carlossanlop commented Jan 29, 2021 •

edited

Loading