roslyn: Proposal: Automatic documentation for potential exceptions

Currently you can carelessly throw exceptions without any documentation for the client unless you manually write <exception> doc tags above the method. I suggest to automate this so that all potential exceptions would be added to method’s doc automatically and Quick Info can show them.

/// <exception cref="ExceptionA"></exception>
void F() => throw new ExceptionA();
/// <exception cref="ExceptionB"></exception>
void G() => throw new ExceptionB();
/// <exception cref="ExceptionA"></exception>
/// <exception cref="ExceptionB"></exception>
void H() { F(); G(); }

->

void F() => throw new ExceptionA();
void G() => throw new ExceptionB();
void H() { F(); G(); }

If the method is outside of the assembly boundary, we can infer exception tags from documentation of the used methods.

It would be also helpful if a code fix add those tags to include the descriptions of the reasons why these exceptions could be thrown. I think this can be an alternative to checked exception (a la Java) to encourage people to document exceptions without forcing them to write try catch.

Here you go: https://marketplace.visualstudio.com/items?itemName=YoavFrandzel.CheckedExceptions I’m sure there are cases that are not completely covered, but I think it does what you want in 90% of the cases.

Have you read Joe Duffy’s blog post? He argues a single [Throws] provides enough information for the consumers of your method.

@MgSam

I don’t think that’s necessarily a problem. Java checked exceptions work in the same manner. You’re expected to document those exceptions that would be thrown due to a breakdown in the method logic, not those that might result due to programmer error or virtual machine failure.

Since this is just an informative analysis and there would be no guarantee in the same sense of checked exceptions, I’d agree that it should not be built into the compiler. I don’t know if Roslyn provides any mechanism to do this transparently along the compilation process.

Visual Studio 2022 with C# now auto-completes the summary comments with any exceptions. Adding this analyzer would go great with that feature to cleanup old code.

This doesn’t work if used with for example ArgumentNullException.ThrowIfNull(obj) It overall doesn’t seem to work if there is no throw keyword in the method

Visual Studio 2022 with C# now auto-completes the summary comments with any exceptions. Adding this analyzer would go great with that feature to cleanup old code.

@alrz The reason why I think xml docs are not a good underlying mechanism to persist this information is that there is no guarantee that the exception information is reliable. Maybe I didn’t use the latest version of Visual Studio and the exception information is misleading if you were expecting it to be generated in general. It would be much higher fidelity to calculate all this and augment the XML docs on the consumer side automatically in the IDE along with IntelliSense.

I like this proposal. It would be great to have a warning for missing exception documentation and a quick fix to insert all individually known exceptions, just like how <params> works today. I’m using this which might interest you: https://github.com/CSharpAnalyzers/ExceptionalReSharper But if it’s implemented officially and without the ReSharper dependency, all the better.

Statically, if you know what exception types F and G and AnotherMethod can throw, even catch (Exception) { throw; } will only ever throw one of those known types.