Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

SA1611 ignores included documentation #3173

Closed
angelobreuer opened this issue Jul 22, 2020 · 1 comment · Fixed by #3174
Closed

SA1611 ignores included documentation #3173

angelobreuer opened this issue Jul 22, 2020 · 1 comment · Fixed by #3174
Assignees

Comments

@angelobreuer
Copy link
Contributor

The code below produces a violation of SA1611 (ElementParametersMustBeDocumented):

Program.cs

/// <summary>
/// Gets the content of the specified uri as a stream asynchronously.
/// </summary>
/// <param name="uri">the request URI.</param>
/// <returns>
/// A <see cref="Task{TResult}"/> representing the result of the asynchronous operation.
/// </returns>
/// <include file="docs.xml" path="/docs/CancellationToken/*"/>
public Task<Stream> GetContentAsync(Uri uri, CancellationToken cancellationToken = default)
{
     // [...]
}

docs.xml

<?xml version="1.0" encoding="utf-8" ?>
<docs>
  <CancellationToken>
    <param name="cancellationToken">
      a cancellation token used to propagate notification that the asynchronous operation
      should be canceled.
    </param>
    <exception cref="System.OperationCanceledException">
      thrown if the cancellation token has had cancellation requested
    </exception>
  </CancellationToken>
</docs>

I think the analyzer should read the docs.xml file and include the documentation from it but instead, it shows a warning:
warning SA1611: The documentation for parameter 'cancellationToken' is missing.

This issue only occurs when some of the parameters are documented in the included and some of the parameters are documented "above the method". IntelliSense recognizes the parameters even if they are documented in different places.

I've also created a repository that shows how to reproduce the issue: https://github.com/angelobreuer/SA1611Repro

Thanks in advance!

@angelobreuer
Copy link
Contributor Author

Grabbing this

angelobreuer added a commit to angelobreuer/StyleCopAnalyzers that referenced this issue Jul 23, 2020
angelobreuer added a commit to angelobreuer/StyleCopAnalyzers that referenced this issue Jul 23, 2020
@vweijsters vweijsters added this to the 1.2-beta.next milestone Jul 28, 2020
sharwell added a commit that referenced this issue Jul 30, 2020
#3173 - SA1611 ignores included documentation
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants