Use record param docs as property summary docs #58960
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
RikkiGibson
force-pushed
the
record-xml
branch
2 times, most recently
from
c78fed4 to
77dca02
Compare
RikkiGibson
force-pushed
the
record-xml
branch
from
77dca02 to
6b37199
Compare
RikkiGibson
commented
Jan 27, 2022
...ompilers/CSharp/Portable/Compiler/DocumentationCommentCompiler.DocumentationCommentWalker.cs
Outdated
Show resolved
Hide resolved
RikkiGibson
commented
Jan 27, 2022
...ompilers/CSharp/Portable/Compiler/DocumentationCommentCompiler.DocumentationCommentWalker.cs
Outdated
Show resolved
Hide resolved
RikkiGibson
commented
Jan 27, 2022
| { | ||
| if (attribute is XmlNameAttributeSyntax nameAttribute | ||
| && nameAttribute.GetElementKind() == XmlNameAttributeElementKind.Parameter | ||
| && string.Equals(nameAttribute.Identifier.Identifier.ValueText, recordPropertySymbol.Name, StringComparison.Ordinal)) |
There was a problem hiding this comment.
We could consider actually binding the attribute value and comparing the resulting symbol with the record property symbol, but it doesn't seem necessary.
jcouv
reviewed
Jan 31, 2022
| @"<member name=""P:C.I1""> | ||
| <summary>Description for I1</summary> | ||
| </member> | ||
| ", property.GetDocumentationCommentXml()); |
There was a problem hiding this comment.
Could you update the test below (XmlDoc_Cref) to check the doc on generated property too?
More cases of references (cref/seealso/...) would be good to cover, if we don't have it already: one parameter/property referencing another parameter/property.
jcouv
reviewed
Jan 31, 2022
| @@ -706,7 +777,6 @@ private string FormatComment(string substitutedText) | |||
| Debug.Assert(numLines > 0); | |||
| } | |||
|
|
|||
| Debug.Assert(TrimmedStringStartsWith(lines[0], "/**")); | |||
There was a problem hiding this comment.
nit: Consider adding a comment to replace the assertion (we may have /** or a positional property case)
jcouv
reviewed
Jan 31, 2022
| { | ||
| _cancellationToken.ThrowIfCancellationRequested(); | ||
|
|
||
| if (getMatchingParamTags() is not { } paramTags) |
jcouv
reviewed
Jan 31, 2022
CyrusNajmabadi
approved these changes
Feb 2, 2022
chsienki
approved these changes
Feb 2, 2022
ghost
added this to the
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Closes #52663
This solution works by modifying the processing stage where crefs are replaced with doc comment IDs.
It requires some changes to the subsequent 'FormatComment' step which removes
///,/**and similar exterior trivia, and adjusts the indenting of the comments to match the output XML file. Specifically, make a change to make this layer more tolerant of "fragments" of/** */multi-line comments.In the medium or long term, I'd actually like to eliminate or vastly simplify the 'FormatComment' stage by modifying the initial parsing stage of XML comments. Ideally, we would have an invariant where:
Then I think we could write the XML to the documentation stream in one pass, simply replacing cref nodes with doc comment IDs as we go and inserting the appropriate amount of indentation immediately following each XmlNewLineToken.