我应该如何记录继承的成员？

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。