Fix the xml doc issue when the parameter's actual name is not the same as their variable name#5615
Merged
ArcturusZhang merged 13 commits intomicrosoft:mainfrom Jan 16, 2025
Conversation
03ff293 to
bad4f99
Compare
63f7453 to
4a7047e
Compare
Collaborator
|
API change check API changes are not detected in this pull request. |
ArcturusZhang
commented
Jan 15, 2025
ArcturusZhang
commented
Jan 15, 2025
packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Writers/CodeWriter.cs
Show resolved
Hide resolved
ArcturusZhang
commented
Jan 15, 2025
...es/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Statements/XmlDocStatement.cs
Show resolved
Hide resolved
ArcturusZhang
commented
Jan 15, 2025
...ient-csharp/generator/Microsoft.Generator.CSharp.ClientModel/src/Providers/ClientProvider.cs
Show resolved
Hide resolved
ArcturusZhang
commented
Jan 15, 2025
packages/http-client-csharp/generator/Microsoft.Generator.CSharp/src/Shared/StringExtensions.cs
Show resolved
Hide resolved
...ent-csharp/generator/Microsoft.Generator.CSharp/test/Statements/XmlDocParamStatementTests.cs
Show resolved
Hide resolved
...csharp/generator/Microsoft.Generator.CSharp.ClientModel/src/Primitives/ScmKnownParameters.cs
Show resolved
Hide resolved
JoshLove-msft
approved these changes
Jan 15, 2025
This file contains hidden or 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
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.
Fixes #5565
Fixes #5567
Fixes #5568
The root cause of the issue here is:
the
ParameterProviderhas aNameproperty, but it is actually the name of its input parameter, not its actual name in the code which we will never know until we actually write them into the code (because of the scope stuff and name collisions)Therefore, this PR added a scope version of
WriteXmlDocsand allows the parameters to be declared in the xml doc.For a method, the parameters first appear in the xml docs, and then the method signature, therefore allowing the xml doc part to declare the parameter actually makes sense - since our code writer could only go forwards, no backwards.
With this change, if there is xml doc, when the code writer writes the xml doc for a parameter, if the parameter has a "not declared"
CodeWriterDeclaration, it will declare it with the current scope (which is basically the same scope of the method), and then when it writes the method signature, it will find those parameters have been declared and it will just use the name, therefore everything works fine.If there is no xml doc, when the code writer writes the method signature, it will find those parameters are not declared yet, and declares them. This is the same logic before this change.
To achieve this, this PR has to change the start tag and end tag in the
XmlDocProviderto beFormattableStrings. This allows us to utilize the ability ofCodeWriterto automatically resolve the declaration of the parameter inside the tag.