Auto-generating documentation and Inheritence

Question

I have the base API controller:

 public class BaseController<T> : ApiController
{
    /// <summary>
    /// Method GetByYear in Base class
    /// </summary>
    /// <param name="year"></param>
    /// <returns></returns>
    public virtual IQueryable<T> GetByYear(int year)
    {
        return null;
    }
}

and child that just inherited method GetByYear from base:

public class HouseController : BaseController<House>
{
    /// <summary>
    /// Method Test
    /// </summary>
    /// <returns></returns>
    public string Test()
    {
        return "Test";
    }
}

I use Help page to create auto documentation. And in result I get:

I want to get a description of the two methods.
How can I get XML comments to the method GET in child class without overriding?
Or should I copy it to my child class?

When I use <inheritdoc /> in HouseController I get the same result as above, and I do not want to override each method when it is not needed:

     /// <inheritdoc />
    public override IQueryable<House> GetByYear(int year)
    {
        return base.GetByYear(year);
    }

Another question: How can I use ghostdoc with default Help page?

You're asking if you should document derived classes and overrides? Um... yes. You do _not_ need to document inherited members that are not overidden. — D Stanley, Sep 01 '15 at 22:36

score 1 · Answer 1 · answered Sep 01 '15 at 22:37

1

You can use /// <inheritdoc />.

answered Sep 01 '15 at 22:37

Richard Schneider

34,944
9
57
73

Yes, but for use that I also have to override base methods. I want to leave the body empty of child class if there is no need overriding – Sep 01 '15 at 22:39
@D.Joe I wouldn't bother, though - your documentation generator should give you a link to the base class., Documenting only overridden and new methods actually makes the docs more useful. – Reed Copsey Sep 01 '15 at 22:41
I need a solution as in [this](http://stackoverflow.com/a/32342008/5246440) answer. But it does not work for me ((. – Sep 01 '15 at 22:48
Could you please help me? – Sep 08 '15 at 20:59

score 0 · Answer 2 · answered Sep 01 '15 at 22:42

0

It may depend on the program that turns XML comments to actual documentation, but MSDN's, for example, just replicates the base documentation, noting that it is inherited from the base class. So you do not need to replicate the documentation on derived members (unless they are overridden and behave differently, thus requiring different documentation)

answered Sep 01 '15 at 22:42

D Stanley

149,601
11
178
240

Thanks. It is a very god news but why does it not work for me? – Sep 01 '15 at 22:45
You'll have to be more specific - what _exactly_ isn't working? What are you using to generate the actual documentation? (Please add to your question, not as a comment) – D Stanley Sep 01 '15 at 22:52
Could you please help me? – Sep 08 '15 at 14:59

Auto-generating documentation and Inheritence

2 Answers2