Documenting inherited polymorphic method

Apr 5, 2011 at 10:44 AM

How should I document the following situation, which I hope I can explain clearly?


I have a base class public instance method that calls internal polymorphic instance methods (ie. marked virtual in base class and overridden in derived class).  By this means, the derived class inherits what is effectively a polymorphic method.  It also inherits the xml documentation of this method but this unfortunately describes the behaviour of the method in the context of the base class, not the context of the inheriting class.


I suppose what I want to do is somehow override the inherited documentation.  The trouble is I have no method in the derived class to which I can attach the xml comments.  Any suggestions will be welcome.



Apr 5, 2011 at 4:03 PM

Inherited members only show up on the member list pages for the derived class.  The links on those pages will take you to the base class's method.  Without a method in the derived class, there's no way to "override" the base class documentation.  One possible solution is to put a note in the inherited member's remarks to see the documentation on the derived classes for details on changes in behavior for their particular context and then put such comments in the remarks on the derived classes themselves (the XML comments on the derived class declarations).



Apr 5, 2011 at 4:43 PM

Thanks for your as ever helpful reply.  Your remark about there being no way to "override" the base class documentation without a method in the derived class confirms what I had feared.  Adding remarks in both the base and derived class as you suggest is a possible but not elegant solution (IMO).


I guess in posing the question I was “fishing” for some thoughts on whether there is a need for a general means of “extending/overriding” the comments attached to inherited members – possibly with some kind of “false” or “pseudo” target tag.  It’s sort of like what you can already do with the <inheritdoc /> tag, but for already inherited documentation.  Or is what I’m thinking beyond the pale?




Apr 5, 2011 at 8:46 PM

In theory, I suppose it's possible that you could write a plug-in or tool that would search the XML comments for some sort of "overrideMemberDoc" tag and insert a fake member into the derived class's reflection information by cloning the inherited member's information so that the comments could be attached to it in the derived class.  The comments would most likely have to be managed in a standalone XML comments file unless you could find a way to include them in the code for the class sort of like the NamespaceDoc class support in SHFB.



Apr 5, 2011 at 11:11 PM

Food for thought – many thanks.


I guess the need for this is not all that common.  The pragmatic solution in my case is to just override the inherited members to give me something to which I can attach the new comments.  These overrides do nothing but simply call their overridden base class method - somewhat redundant but pragmatic.