Search code examples
c#documentationdryfluent-interface

DRY in C# code documentation on two interface variants

I am currently rewriting a SDK to access a webservice.

Since the model for a database query consists of many classes (actually one class for each of about twenty possible filters), I decided to provide a fluent interface additonally.

So instead of

new Query(
 Age = new AgeFilter() { From = 18, To = 65 },
 Location = new PostalCodeFilter() { Zip = 12345, new RadiusDefinition() { ... } }
);

the user can now write:

Query.Create()
  .WithAge(18, 65)
  .WithLocation(12345, 50, "miles");

Now I found out that the traditional way has to be included as well (I cannot hide the actual objects as internal).

How can I avoid having to document both the parameters of the fluent interface and the fields of the data classes? The descriptions are the same. I thought about see/seealso but this wouldn't show up in Visual Studio's Code Assistant.

Solution

  • If you use Sandcastle you can use the <inheritdoc /> tag just like this:

    ///<param name="from">
///<inheritdoc cref="AgeFilter.From" select="/summary/node()" />
///</param>

    or

    ///<summary>
///<inheritdoc cref="QueryFilters.WithAge" select="/param[@name='from']/node()"/>
///</summary>