Automatically document exceptions on methods based on methods it's calling

[pascalberger]

DocFX Version Used:
2.40.7

Template used: (default or statictoc or contain custom template)
default

Steps to Reproduce:

n/a

Expected Behavior:

It would be nice to have the possibility that DocFx could automatically document exceptions on a method based on the documented exceptions on methods it's calling.

Actual Behavior:

Currently I can document possible exception using the exception XML comment tag. This needs to be done manually on all methods, which is duplicated work if exceptions thrown in methods called by the method should also be documented.

[pascalberger]

@BillWagner

[yufeih]

To do this, docfx needs to consume a static call graph of every method. Currently the csharp compiler does not produce that static call graph, and I doubt if it could if you consider non-static class like delegates, interface calls, virtual calls...

This feels unlikely to happen unless charp has checked exceptions

[BillWagner]

I was chatting with @pascalberger about this request during the C# workshop at NDC. We were wondering if there is a simpler feature that provides a lot of the benefit with much less engineering work for docfx (and the language).

@yufeih is correct that to completely solve the problem you'd need checked exceptions, and you'd still need to make assumptions about the environment and the stability of everything in the system. That's clearly out of scope.

Instead, consider if docfx or the compiler could build a static call graph that only went as deep as the methods in the current assembly. Then, the <exceptions> section could include the union of the exceptions from those methods.

Consider this as the key scenario:

1. I create a DoesImportantWork() method. I quickly find that there are 3 common overloads with different arguments. Maybe one takes a struct that has all the necessary information, another has individual arguments for that information, a third gets the needed information from the environment.

As an implementation detail, all three of those methods are implemented in one of the overloads. That implies that the list of exceptions possible could be taken from that one method declaration. As implemented today, developers need to copy and paste that common exception list into all the overloads. A feature that solved just that scenario would be very valuable.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week if no further activity occurs.

[KalleOlaviNiemitalo]

If DocFX supported the cref and select attributes of inheritdoc (#1306), one could use that.

/// <exception cref="FileNotFoundException">
///  There is no file at <paramref name="path"/>.
/// </exception>
/// <exception cref="ArgumentOutOfRangeException">
///  <paramref name="fudgeFactor"/> is not positive.
/// </exception>
void DoesImportantWork(string path, float fudgeFactor)
{
    // …
}

/// <inheritdoc cref="DoesImportantWork(string, float)"
///             select="exception[not(.//paramref/@name='fudgeFactor')]"/>
void DoesImportantWork(string path)
{
    DoesImportantWork(path, 1.0);
}

This also demonstrates that not all exceptions apply to all overloads.

[pascalberger]

@BillWagner

[yufeih]

To do this, docfx needs to consume a static call graph of every method. Currently the csharp compiler does not produce that static call graph, and I doubt if it could if you consider non-static class like delegates, interface calls, virtual calls...

This feels unlikely to happen unless charp has checked exceptions

[BillWagner]

I was chatting with @pascalberger about this request during the C# workshop at NDC. We were wondering if there is a simpler feature that provides a lot of the benefit with much less engineering work for docfx (and the language).

@yufeih is correct that to completely solve the problem you'd need checked exceptions, and you'd still need to make assumptions about the environment and the stability of everything in the system. That's clearly out of scope.

Instead, consider if docfx or the compiler could build a static call graph that only went as deep as the methods in the current assembly. Then, the <exceptions> section could include the union of the exceptions from those methods.

Consider this as the key scenario:

1. I create a DoesImportantWork() method. I quickly find that there are 3 common overloads with different arguments. Maybe one takes a struct that has all the necessary information, another has individual arguments for that information, a third gets the needed information from the environment.

As an implementation detail, all three of those methods are implemented in one of the overloads. That implies that the list of exceptions possible could be taken from that one method declaration. As implemented today, developers need to copy and paste that common exception list into all the overloads. A feature that solved just that scenario would be very valuable.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed in a week if no further activity occurs.

[KalleOlaviNiemitalo]

If DocFX supported the cref and select attributes of inheritdoc (#1306), one could use that.

/// <exception cref="FileNotFoundException">
///  There is no file at <paramref name="path"/>.
/// </exception>
/// <exception cref="ArgumentOutOfRangeException">
///  <paramref name="fudgeFactor"/> is not positive.
/// </exception>
void DoesImportantWork(string path, float fudgeFactor)
{
    // …
}

/// <inheritdoc cref="DoesImportantWork(string, float)"
///             select="exception[not(.//paramref/@name='fudgeFactor')]"/>
void DoesImportantWork(string path)
{
    DoesImportantWork(path, 1.0);
}

This also demonstrates that not all exceptions apply to all overloads.