CODEWITHSUNDEEP
c#sandcastle
vlada
vlada

Reputation: 165

inheritdoc specific exception using cref

How to use <inheritdoc/> to inherit specific exception from another method. Is it possible to do something like this:

/// <summary>
/// Summary
/// </summary>
/// <inheritdoc cref="Method2(int)" select="exception[@cref='CustomException']" />
public int Method1()
{
    return Method2(1);
}

/// <summary>
/// Summary...
/// </summary>
/// <exception cref="ArgumentException">
/// ArgumentException...
/// </exception>
/// <exception cref="CustomException">
/// CustomException...
/// </exception>
public int Method2(int count)
{
    // do something
}

When I build documentation and open it, there is no exception for Method1. Currently, my workaround is to add id="CustomException" to Method2 and use <inheritdoc cref="Method2(int)" select="exception[@id='CustomException']" />

Upvotes: 6

Views: 891

Answers (1)

Galactus
Galactus

Reputation: 91

According to the documentation, the syntax using inheritdoc without Sandcastle would be:

<inheritdoc cref="Method2(int)" path="/exception[@cref='CustomException']"/>

The Sandcastle documentation indicates the select attribute has been deprecated as of November 2019 (I know the question dates from before that, but that's the current situation). The equivalent path attribute should be used instead:

<inheritdoc cref="Method2(int)" path="exception[@cref='CustomException']"/>

The main difference between using Sandcastle or not is the forward slash that the xpath value of the path attribute starts with.

I have no experience using Sandcastle myself, but I came across this question when searching for an issue myself: it appears as if the cref attribute is not fully supported as a selector in the xpath expression of the inheritdoc path attribute. Using path="/exception" inherits all the exception documentation for me, but when using path="/exception[@cref='CustomException']" no exception documentation is inherited, and when negating it with path="/exception[not(@cref='ArgumentException')]" all the exception documentation is inherited. I have not been able to find any information about this behavior anywhere; probably because cref is an attribute of inheritdoc as well...

Upvotes: 1

Related Questions