How should I document a inherited members?

views:

answers:

+1 Q:

How should I document a inherited members?

Consider that I have a complex class structure where many elements inherit from other elements. I may have a method GetStuff(string stuffName, int count) defined in an interface, which is inherited by other interface, which is then implemented abstractly by an abstract class, which is then implement explicit in a concrete class etc. etc...

How should I handle inherited members such as GetStuff() when documenting my code with XML comments which will be used with a tool such as Doxygen or Sandcastle? It seems wrong to just copy and paste the same description at each level. Should I be considering a different audience at the interface level vs the concrete class level? For example the documentation for GetStuff() at the interface may consider people implementing the interface, whereas the documentation at the concrete level may instead consider people who will be using the class?

+1 A:

Document the interface method according to its code contract. Do not comment on its implementation, only on its semantic purpose, i.e. what it’s supposed to do, not how. The audience for this documentation is both your implementors and your users: the method will both be implemented as well as called.
Document the abstract method simply by saying that it implements the interface method and linking to it. There is nothing extra to be said about it, and duplicating the comment violates the DRY (Don’t Repeat Yourself) principle: you would have to remember to make any change to it in both places. (Of course, in the case of an abstract method that doesn’t implement an interface method, document it in the same way that you would document an interface method.)
Document the concrete implementation by saying that it implements the interface method and/or that it overrides the abstract member. Optionally add information about its implementation if it is relevant to the caller — for example, its performance characteristics, or situations in which it might throw, etc.

Timwi 2010-08-21 03:38:20

Ok so if I wanted to document on a specific implementation I would do that within the body of a concrete version of the method right?

Eric Anastas 2010-08-21 03:50:08

Isn't there some distinction between what consumers of an abstract member will want to know vs what implmentors will want to know? For example say I have an abstract method AddWidget(Widget w) method. I may want concrete implmentations to do a number of things such as validate the new Widget, update a log, and fire an Event. A consumer of the method, however, probably wont care about all that, and only needs to know that the purpose of the method is to add a new Widget.

Eric Anastas 2010-08-21 03:57:53

@Eric: You are right about abstract members that are somewhat delicately linked to implementation details already contained in the abstract class which require the override to do certain things. In those cases, of course you need to document that even though the caller might not care about it. However, in *interface* methods this shouldn’t matter; interfaces shouldn’t care about implementation details.

Timwi 2010-08-21 04:07:13

what you are saying makes perfectly sense

camilin87 2010-08-21 03:39:10

ansaurus

tags:

views:

answers:

How should I document a inherited members?

related questions