Should XML doc notes be on Interface or Implementation for WCF service using Sand Castle?

Question

I've never used SandCastle before, so I've got a kind of noob question.

I'd like to document a WCF service, and I'd like to use SandCastle to do it. Should the doc notes be at the Interface level on the OperationContracts, or should they be on the methods in the Implementation class? Or both?

Answer 1

This is mostly a personal/team choice, depending on your needs and desires.

I have used Sandcastle to document both the interface and the implementing class. I did this for internal documentation for my team, not for external clients of the service - I provided a different document for them.

The reason I'd recommend both is that two different classes could implement the same contract in entirely different ways. Keep the code documentation on the interface fairly simple, and then in the implementing class(es) give more documentation (remarks, code examples, etc) that cover the implementing class' functionality.

This will allow other developers (or yourself down the road) to understand what the interface offers (requires), as well as what/how the implementing class implements the functionality specified in the interface.