Jump to content
  • Advertisement
Sign in to follow this  
Trillian

[.net] [C#] Delegating documentation to base class.

This topic is 3663 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

Hello! When overriding a member from a base class, what is the correct way to have the C# compiler copy the documentation from the base class' member and add "(inherited from ***)"? Example :
class Foo
{
    /// <summary>Bars this foo</summary>
    public abstract void Bar();
}

class Frob : Foo
{
    /// ?
    public override void Bar() {}
}

Share this post


Link to post
Share on other sites
Advertisement
Implement that functionality into the tool you use to generate the HTML/whatever docs from the comment XML.

If you don't generate documentation from the XML, use something like GhostDoc instead, as it understands the inheritance relationships and will copy documentation for you.

Share this post


Link to post
Share on other sites
I'm currently using sandcastle to generate my documentation (I don't want to code my own tool for this) and it seems that it indeed generates those "inherited from ***" when I put no documentation on the overriden member. I was thinking that this might not be the best way to do it as the C# compiler emitted warnings about uncommented public members for overriden members. So my question is actually more about finding a way to keep this behavior (the generation of "inherited from ***") while suppressing that annoying warning. Is ignoring that warning is my only option?

Oh and, as much as I'd like using GhostDoc, I can't with my express SKU. I actually tried installing it yesterday.

Share this post


Link to post
Share on other sites
All that documentation management can be quite troublesome. It's not just useful to put the documentation at the super class, but also at the interface level. All those tools really don't handle it the best way, and it's a nightmare to copy/paste/maintain the documentation everywhere.

Could MonoDoc's[1] approach be the best one? Anyone tried it for real?

[1] http://www.mono-project.com/Monodoc

Share this post


Link to post
Share on other sites
Off-topic, I apologize:
I find that documenting in code is a good thing at the class level; e.g., displaying the summary using Intellisense. I draw the line at library or framework documentation - documentation created at the class/method level is incomplete because it fails to give a worthwhile vantage point for understanding the system as a whole.

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

We are the game development community.

Whether you are an indie, hobbyist, AAA developer, or just trying to learn, GameDev.net is the place for you to learn, share, and connect with the games industry. Learn more About Us or sign up!

Sign me up!