So we have an interface like so
/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
/// <summary>
/// Creates foos
/// </summary>
void Create(Foo foo);
/// <summary>
/// Does Bar stuff
/// </summary>
void Bar();
}
Recently, we played a documentation story which involved generating and ensuring that there is plenty of XML documentation like above. This caused a lot of duplication of documentation though. Example implementation:
/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
/// <summary>
/// Creates foos
/// </summary>
public void Create(Foo foo)
{
//insert code here
}
/// <summary>
/// Does Bar stuff
/// </summary>
public void Bar()
{
//code here
}
}
As you can see the method documentation is a straight rip from the interface.
The big question is, is this a bad thing? My gut tells me yes because of duplication, but then again maybe not?
Also, we have other similar documentation duplication with override
functions and virtual
functions.
Is this bad and should be avoided, or not? Is it at all worthwhile even?
4
In general, I’d only add new documentation to the implementation’s methods if there’s something specific about that implementation that needs to be mentioned.
In javadoc you can link to other methods, which would allow you to just create a link in the implementation to the method documentation in the interface. I think this is how it’s supposed to be done in .Net (based on my reading the online documentation, not my own experience):
/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
/// <summary>
/// Creates foos
/// </summary>
void Create(Foo foo);
/// <summary>
/// Does Bar stuff
/// </summary>
void Bar();
}
/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
/// <summary>
/// <see cref="ICreatesFoo.Create(Foo)"/>
/// </summary>
public void Create(Foo foo)
{
//insert code here
}
/// <summary>
/// <see cref="ICreatesFoo.Bar()"/>
/// Also Note: Implementation of Bar() in FastFooCreator
/// requires a minimum of 512 MB RAM to Bar the Foo.
/// </summary>
public void Bar()
{
//code here
}
}
The documentation for the <see/>
element: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx
1