Proposal: Automatic documentation for potential exceptions

[alrz]

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.

[svick]

How do you figure out which exceptions can be thrown in the presence of arbitrarily complex catch clauses and rethrow statements?

Consider e.g.:

void H()
{
    try
    {
        F();
        G();
    }
    catch (Exception ex)
    {
        if (AnotherMethod(ex))
        {
            throw;
        }
    }
}

Here, the compiler wouldn't be able to figure out which exception can actually be thrown by the method and it will either report exceptions that won't be thrown by the method or not report exceptions that can be thrown (or both).

I'm not sure how useful would an imperfect implementation like that be.

[alrz]

@svick This will work on static type of exceptions, so your method will likely throw an exception of type Exception plus whatever AnotherMethod throws, if any. I think that's enough for developer to know that's a potential failure. If you want more specific exception types, you should wrap, not rethrow.

[jnm2]

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.

[alrz]

@jnm2 Sorry, human mistake. :D That's why I like this to be generated by the compiler.

[jnm2]

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.

[DavidArno]

I'm confused how you would automate this and where the code fix comes into it. Your code example implies one could remove these comments and have them auto-generated somehow so that they appeared in Quick Info. But a code fix implies they'd be added to the source if missing.

Could you clarify, please?

[alrz]

@DavidArno The explicit exception documentation (which can be added by the code fix) is only required if you want to write descriptions of the reasons why these exceptions could be thrown (inside <exception> tag). Otherwise, it should report potential exception types in Quick Info without any xml doc tag (meaning that the exception tags will be emitted by the compiler under the hood just as if they were written with an empty body).

[jnm2]

As a consumer I'd like this automated feature because I'd like to know what the API might do, but the problem could be that I'd rely too heavily on it having been generated. As a consumer, I think it would be better if the static analysis was done by the IDE and presented in addition to the doc comments so that you don't have to rely on the author's generation process (and version of compiler).

As an author, I want to write meaningful explanations of why each exception might occur. Adding empty nodes under the covers doesn't help me achieve that goal, but an analyzer warning would be fantastic with a code fix that inserts the node in my source code and positions my cursor to tab through and type descriptions.

[alrz]

@jnm2 Most of the time just exception types suffice as one can have an idea of what exceptions could be thrown — in fact, to this day, it's not supported to show exception reasons in Quick Info (#1515). Besides, in my opinion, writing documentation is a far more involved process and developers are often too lazy to do that! So, having the compiler figure out the exception types would be a big step to start. This doesn't necessarily discourage people to write meaningful explanations. I'd agree that an optional warning for missing exception docs can be helpful if you take that as a convention for your codebase.

[HaloFour]

This sounds like something that could be accomplished via an analyzer, albeit a potentially complicated one. I've not done much work with analyzers. Can they access the XML documentation of either referenced libraries or annotated methods within the current project?

[alrz]

@HaloFour Sure, but at best they can suggest to add xml doc comments. As a language feature, it would be totally transparent to the programmer. Otherwise you need to manually run the fix to update xml docs every time code changes.

[HaloFour]

@alrz

You'd need to enable XML docs for any of this to work as described anyway. Seems like a poor-man's implementation of checked exceptions. If we're going to wade in that direction I'd rather see it "done right", although if I recall the team expressed no desire to implement checked exceptions.

[alrz]

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.

[MgSam]

I think a problem with this is that any such list of exceptions that Roslyn might generate would either be noisy or preclude important cases. NREs, StackOverflowException, OverflowException can potentially happen anywhere.

Another problem is exceptions that are re-used for different things for different purposes- such as InvalidOperationException. The IDE can tell you that this might be thrown but in absence of documentation you have no way of knowing if this is from the .Single() extension method and never will fail or is from a source that you need to catch and potentially handle.

[HaloFour]

@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.