CODEWITHSUNDEEP
c#xmlvisual-studio
KulaGGin
KulaGGin

Reputation: 1249

How to document overloaded methods with the same XML comments?

I know there are questions like this, but they're old. So I'm creating a new one.

At the moment when there are 3 overloaded methods I have to do this:

/// <summary>
/// Description that described summary of an overloaded method.
/// </summary>
/// <param name="fileName">Description that describes filename parameter</param>
/// <param name="options">Description that describes options parameter</param>
/// <returns>Description of what method returns</returns>
public bool ReadFrom(string fileName, ReaderOptions options = null) {
    return false;
}

/// <summary>
/// Description that described summary of an overloaded method.
/// </summary>
/// <param name="stream">Description that describes stream parameter</param>
/// <param name="options">Description that describes options parameter</param>
/// <returns>Description of what method returns</returns>
public bool ReadFrom(Stream stream, ReaderOptions options = null) {
    return false;
}

/// <summary>
/// Description that described summary of an overloaded method.
/// </summary>
/// <param name="rawData">Description that describes rawData parameter</param>
/// <param name="options">Description that describes options parameter</param>
/// <returns>Description of what method returns</returns>
public bool ReadFrom(byte[] rawData, ReaderOptions options = null) {
    return false;
}

And I would like to have something like this:

#region overloadedReadFromMethods
/// <summary>
/// Description that described summary of an overloaded method.
/// </summary>
/// <param name="fileName">Description that describes filename parameter</param>
/// <param name="options">Description that describes options parameter</param>
/// <returns>Description of what method returns</returns>
public bool ReadFrom(string fileName, ReaderOptions options = null) {
    return false;
}

/// <param name="stream">Description that describes stream parameter</param>
public bool ReadFrom(Stream stream, ReaderOptions options = null) {
    return false;
}

/// <param name="rawData">Description that describes rawData parameter</param>
/// <returns>Even considering that returns tag is present on the first overloaded method,
/// this overloaded method shows this specific description.
/// </returns>
public bool ReadFrom(byte[] rawData, ReaderOptions options = null) {
    return false;
}
#endregion overloadedReadFromMethods

So the first overloaded method describes default description and then methods below can override it with their own descriptions. I want it to show in Visual Studio's IntelliSense.

Upvotes: 3

Views: 1024

Answers (3)

Dariusz Woźniak
Dariusz Woźniak

Reputation: 10350

inheritdoc

The inheritdoc attribute along with cref attribute works very well for me. JetBrains Rider properly generates documentation for all the methods.

Example usage:

/// <inheritdoc cref="Foo(string?,string?,Guid)"/>
Result<IBar> Foo(string? x, string? y);

/// <summary>
/// Here comes the original comment
/// </summary>
Result<IBar> Foo(string? x, string? y, Guid id);

Upvotes: 1

Funwie
Funwie

Reputation: 91

I think the extra work to document each method is necessary because they all have different signatures. Methods have different <param></param>

InheritDoc is a package that can be used to inherit xml docs.

Upvotes: 2

Athanasios Kataras
Athanasios Kataras

Reputation: 26430

TLDR - It's not possible

Long story short, as was the case in the past, you still cannot re-use comments this way.

Some interesting ideas here

  1. Create one function with optional parameters. While this would mitigate the problem, I find that optional parameters are sometimes incovenient themselves as they overcomplicate the logic inside and make unit testing very difficult. Overaloading in your case make sense, so this solution does not apply.

  2. Use the <overloads> comment. I can't see it in the official documentation though

  3. Use the <see> and <seealso> xml tag to use reference

Use the <include> tag

This is still not a solution but it allows you to have separate xml documents and handle overall. include documentation

Upvotes: 3

Related Questions