5

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

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

4

2 回答 2

5
  • 根据其代码协定记录接口方法。不要评论它的实现,只评论它的语义目的,即它应该做什么,而不是如何做。本文档的受众既是您的实现者,也是您的用户:该方法将被实现和调用。

  • 简单地说明抽象方法实现了接口方法并链接到它,从而记录抽象方法。对此没有什么可说的,并且复制评论违反了 DRY(不要重复自己)原则:您必须记住在两个地方都对其进行任何更改。(当然,对于没有实现接口方法的抽象方法,以与记录接口方法相同的方式记录它。)

  • 通过说它实现接口方法和/或覆盖抽象成员来记录具体实现。如果它与调用者相关,可以选择添加有关其实现的信息——例如,它的性能特征,或者它可能抛出的情况等。

于 2010-08-21T03:38:20.547 回答
2

Eric Anastas部分帖子 的评论

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

我可以想象只是复制是错误的。但是,可以让 doxygen 为您复制它,然后更改您想要为该实现/范围更改的内容。有关更多信息,您可以查看@copydoc 的描述

于 2011-06-12T02:07:28.087 回答