9

I am using Visual Studio 2013 with ReSharper 8.2.3.

In the code editor, VS will display some information about identifiers under the cursor in a popup box. This information is taken from the Xml API documentation included in the source assembly of the identifier.

Unfortunately, the documentation on exceptions seems to be missing there. Hence, calling the single method of the following class:

public static class ExampleClass
{
    /// <summary>
    /// Does something.
    /// </summary>
    /// <param name="text">The text to process.</param>
    /// <returns>The result.</returns>
    /// <exception cref="ArgumentNullException"><paramref name="text"/> is <see langword="null"/>.</exception>
    /// <exception cref="ArgumentException"><paramref name="text"/> is longer than 50 characters.</exception>
    public static Int32 DoSomething(String text)
    {
        if (text == null)
        {
            throw new ArgumentNullException("text");
        }
        if (text.Length > 50)
        {
            throw new ArgumentException("The text is too long.");
        }

        return 42;
    }
}

will result in the following popup:

popup without exception documentation

Obviously, it is not very helpful for me to know that sometimes, the method might throw an ArgumentException. I thus still have to go find the sources of said class to check out the Xml documentation.

Can some setting in ReSharper or Visual Studio itself be changed so these tooltips display the entire exception information?

Upgrading tool versions is currently not an option for us, unfortunately.

This question is not a duplicate of How to add documentation tooltip to classes, methods, properties, etc. in C#?. In fact, I'd say it's only marginally related. Yes, it also refers to C# and to Xml code documentation. The linked question, however, asks how to mark comments so the C# compiler and IDEs process them as Xml API documentation. This question, in contrast, asks how Visual Studio can be configured to display certain information in its code editor tooltips that is provided in the Xml API documentation, but is missing in these tooltips.

O. R. Mapper
  • 20,083
  • 9
  • 69
  • 114
  • I usually just add error conditions in the main `` description, for my own classes. Not sure if the inbuilt docs for the framework even _have_ that information though. You generally just go to msdn to check that stuff, by pressing `F1` on the function. – Nyerguds Feb 06 '18 at 07:36
  • 2
    @Nyerguds: They do have that information. It's what is generated with the [`` elements](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/exception) in the Xml documentation. The `` element is actually just meant for a very brief overview; it's the text that would appear in in a table in documentation generated by Sandcastle. Hence, putting exception info there doesn't sound like a great idea. But pressing `F1` to open MSDN is not helpful for 3rd-party types, anyway. – O. R. Mapper Feb 06 '18 at 07:45
  • 2
    @GolezTrol: Please explain how this question is a duplicate. The other question appears to ask how to properly formated Xml API documentation. As you can see in my code sample, I am fully aware of how to do that; the issue is that VS chooses not to display some parts of it. – O. R. Mapper Feb 06 '18 at 07:46
  • @GolezTrol: I know how to generate that information - in fact, the code snippet in my question contains an example for that information. While the suggestion that the information sometimes needs to be refreshed after something has changed in the original documentation could be helpful, it is not applicable here, as the documentation text for the exceptions was not added at a later point. It was added at the same time as the `` documentation elements, and as the target instance of VS already displays those, there is no reason to assume that it might be unaware of the text therein. – O. R. Mapper Feb 06 '18 at 09:57
  • @GolezTrol: Sorry, that is definitely not what happens. VS will show the exceptions as listed in the `` tags, which can easily be shown by documenting exceptions that are not thrown in the method. The popup adds the `System` namespace because all identifiers in `cref` attributes in Xml code docs are resolved by the compiler. The popup shows the parameter information from the Xml comment while writing the parameter list. – O. R. Mapper Feb 06 '18 at 10:28
  • @GolezTrol: The compiler has successfully resolved the exception names in the `cref` attributes, because otherwise it would issue a warning. Therefore, just like in non-comment C# source code, there is absolutely no difference between `ArgumentException` and `System.ArgumentException`, as long as the `System` namespace has been made available in a `using` directive. – O. R. Mapper Feb 06 '18 at 10:30
  • 1
    It seems you're right about that. I apologize. I can reproduce the same behavior with VS 2017 and R# 2017.1.3, btw, so upgrading the tools won't do you any good either. I've retracted my close vote and removed the previous comments to free up some space for others to help you out. – GolezTrol Feb 06 '18 at 10:31
  • @GolezTrol: Thanks for pointing that out, even though it takes away one hope that I did have. Let's see whether someone else has found a solution, possibly buried in the endless settings offered by these tools. – O. R. Mapper Feb 06 '18 at 10:32
  • Seems there's a ReSharper plugin to analyse and improve exception documenting (called "Exceptional"), but nothing I read about it seemed to indicate it expanded the normal intellisense tooltips. – Nyerguds Feb 06 '18 at 18:39
  • 2
    VS2019 keeps doing the same thing. I usually add the exception info, as new lines inside the summary with `
    throws
    - when throw contidion
    -     – JotaBe Nov 05 '20 at 11:57
  • 2
    OMG, VS2022 still here - Microsoft, how much time have to pass that you add functionality, which IntelliJ Idea have for years?! – Mic Aug 10 '22 at 12:41

0 Answers0