我应该如何记录继承的成员？ [关闭]

Question

考虑到我有一个复杂的类结构，其中许多元素继承自其他元素。我可能在接口中定义了一个GetStuff(string stuffName, int count)方法，该方法由其他接口继承，然后由抽象类抽象地实现，然后在具体类等中实现显式等等。

在使用与Doxygen或Sandcastle等工具一起使用的XML注释记录我的代码时，我应该如何处理GetStuff()等继承成员？在每个级别复制和粘贴相同的描述似乎是错误的。我是否应该在界面级别与具体级别级别考虑不同的受众？例如，接口上的GetStuff（）文档可能会考虑人们实现接口，而具体级别的文档可能会考虑使用该类的人员？

Answer 1

• 根据代码契约记录接口方法。不要评论它的实现，只是它的语义目的，即它应该做什么，而不是如何做。此文档的读者既是您的实现者又是您的用户：该方法既可以实现也可以调用。
• 简单地通过说明它实现接口方法并链接到它来记录抽象方法。关于它没有什么可说的，重复评论违反了DRY（不要重复自己）的原则：你必须记住在两个地方都做出任何改变。 （当然，在没有实现接口方法的抽象方法的情况下，以与记录接口方法相同的方式记录它。）
• 通过说明它实现接口方法和/或覆盖抽象成员来记录具体实现。如果它与调用者相关，可以选择添加有关其实现的信息 - 例如，它的性能特征，或者它可能抛出的情况等。

Answer 2

part of post对Eric Anastas的评论

在每个级别复制和粘贴相同的描述似乎是错误的。

我可以想象只是复制是错误的。但是，可以让doxygen为您复制它，然后更改您希望为该实现/范围更改的内容。有关更多信息，请查看the description for @copydoc。