I ran into this problem while working on an ASP.net web application using Factory Web Client software (WCSF) in C #, and the same could apply to a different platform and languages. My situation is this:
I define an IView interface for each website / user control based on the WCSF paradigm, then implement an interface of the IView class, implementing each of the methods defined in the interface. When I tried to add xml documentation at the method level, I found that basically I was repeating the same comment content for both the interface method and its counterpart in the implementation class.
So my question is: should there be a significant difference between the contents of the documentation on the interface method and the corresponding class method? Should they emphasize different aspects or something else?
Someone told me that the interface method comment should say “what” the method should do, and the method method comment should say “how” it does. But I remember that I read somewhere that a comment on a level method should only say “what” should use this method, not the detail of the method implementation, since the implementation should not be a problem for users of the method, and this can change.
source
share