Should not warn if exceptions are documented

[just-ero]

Currently, the below code will still produce a warning:

/// <exception cref="System.Exception" />
void M1() { }

/// <exception cref="System.Exception" />
void M2()
{
  M1(); // THROW001
}

It would be great if adding the documentation comment removes the warning.

[sibber5]

@marinasundstrom i could implement this if you agree with the design

[marinasundstrom]

I don't want XML Docs to be the default mechanism for annotating for exceptions. But there might be cases where you want to use the analyzer without adding the ThrowsAttribute to your project. Where you, as a developer, are not allowed to.

We could allow this (exceptions in XML docs) as a flag in the settings file.

The existing checks are pretty easy to find. Just query for the type in cached XML docs. And make sure it's efficient.

Other things that I would like some help with are the code fixes. They are not working right now.

[just-ero]

What settings file is this referring to and why don't you simply use MSBuild project properties?

[marinasundstrom]

I meant: CheckedExceptions.settings.json

But you bring up a good point, this flag/switch might as well be in the project file.

[canton7]

I don't want XML Docs to be the default mechanism for annotating for exceptions.

It would be interesting if you could share your thinking behind that. In my mind, xmldocs have the advantage that they pop up as part of intellisense (so you don't need to go do definition, or wait for the analyser to raise warnings), and they can appear in generated documentation. You're also prompted to say why an exception might be thrown, which is useful information.

If you're writing a library, then you likely want to put exception information into the docs anyway. So now you have to include it twice: once in the attribute, and once in the docs above.

[marinasundstrom]

The point of the ThrowsAttribute is to embed the information in the metadata. That makes it queryable at runtime. It's not always the case that you have the XML doc with the DLL either, unless you package it. I hope people do.

And personally, I find documenting exceptions in XML tedious. While I would like to do it for public APIs. And we can make code fixes for the XML doc part.

I just don't want XML docs to be what is the actual annotation, unless really necessary.

So I'm open for the possibility to use exceptions in XML Docs. But I'm hesitant to make it seen like the default.

[sibber5]

I meant: CheckedExceptions.settings.json

analyzer configuration should probably be done in .editorconfig, but this particular property i think makes sense for it to be also configurable in msbuild. i can change the impl to use .editorconfig and fallback to the json settings file maybe for backwards compat, what do you think?

e.g. it would look something like this:

// .editorconfig
checked_exceptions.ignored_exceptions = System.ArgumentNullException,System.InvalidOperationException
checked_exceptions.informational_exceptions = System.IO.IOException:Propagation,System.TimeoutException:Always

[marinasundstrom]

It doesn't feel right to put this in the editorconfig. I mean the way you would have to express mapping exceptions to report levels there - and potential future options. That is why I created the settings file.

We shouldn't have too many ways to configure something.

But you are welcome to build a prototype and try it out.

[sibber5]

well its sort of the conventional way to configure analyzers in .net, its what all of the official analyzers use for config
https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-files

i personally lean towards following conventions, but of course its your call

[marinasundstrom]

I have concerns about the integrity of the project, and my integrity.

The ThrowsAttribute becomes part of the metadata. Which makes it accessible from code.

Your suggestion to allow exceptions declared XML Docs as being equal to Throws declarations will essentially make ThrowsAttributes obsolete.

The main reason I do support XML docs at the moment is compatibility with the framework.

I do understand there is value in allowing declarations in XML docs. For when you can't add annotations, or even the attribute. But it shouldn't be the main intended way of using the analyzer.

This is my pet project. That is why I'm concerned about the "soul" of this project.

I get that you are looking for standards, but in the case of the analyzer settings, the EditorConfig doesn't suite all the cases for a pleasant developer experience.

As a suggestion, you could fork the project if you want to take it in another direction.

I'm however happy with all the help I can get here.

[sibber5]

thats perfectly fair! i just meant that as a suggestion

good work on the project :)

[marinasundstrom]

@sibber5 I realized that the experience would not even be great with XML docs for declarations.

Adding diagnostics to XML comments is a bit tricky since they are blocks of text. Like for instance when you want to warn about multiple declarations of the same type. How will we find out text spans within such a block.

The C# tooling might already warn you about it, but you might get the idea.

It would add more overhead if we want to go down this route. Since we are already parsing and storing information from loaded XML docs.

---

I have added some new issues for improvements that are worth looking into: A bug fix in code fixes, new diagnostic, and changing some text.

[marinasundstrom]

I added FAQ with a point addressing this issue: here