c# - XML 文档说明是否应该在使用 Sand Castle 的 WCF 服务的接口或实现上？

Question

我以前从未使用过 SandCastle，所以我有一个菜鸟问题。

我想记录一个 WCF 服务，并且我想使用 SandCastle 来完成它。文档注释应该在 OperationContracts 的接口级别，还是应该在实现类中的方法上？或两者？

Answer 1

这主要是个人/团队的选择，取决于您的需求和愿望。

我使用 Sandcastle 来记录接口和实现类。我这样做是为了我的团队的内部文档，而不是服务的外部客户——我为他们提供了不同的文档。

我推荐两者的原因是两个不同的类可以以完全不同的方式实现相同的合同。保持接口上的代码文档相当简单，然后在实现类中提供更多涵盖实现类功能的文档（备注、代码示例等）。

这将允许其他开发人员（或您自己）了解接口提供（需要）什么，以及实现类如何/如何实现接口中指定的功能。