Comment #0 by leandro.lucarella — 2013-06-18T04:18:33Z
Avoiding code duplication is always good. And so is avoiding documentation duplication. When inheriting from a class, and overriding some methods, most of the time it makes no sense to re-rewrite the documentation (usually doing copy&paste from the parent class).
It would be extremely helpful if a series of macros are added to ddoc, with the form $(INHERIT_XXX), where XXX is the name of a section to inherit (special cases like TITLE and DESC could be added). Also adding a $(INHERIT_ALL) to inherit every section from the parent could be useful too.
Examples:
---
/**
* A class
*/
class A
{
/**
* Title for method f
*
* Description for f.
*
* Params:
* x = some int.
*
* See_Also:
* g()
*/
public void f(int x)
{
}
/**
* Title for method g
*
* Description for g.
*
* Returns:
* true if foo, false if bar.
*/
public bool g()
{
}
}
/// Another class
class B: A
{
/**
* $(INHERIT_TITLE)
*
* This method does something else, because this and that. And you shouldn't
* see also g().
*
* $(INHERIT_PARAMS)
*/
public override void f(int x)
{
/* should yield:
* ---
* Title for method f
*
* This method does something else, because this and that. And you shouldn't
* see also g().
*
* Params:
* x = some int.
* ---
*/
}
/// $(INHERIT_ALL)
public override bool f()
{
// documentation will be exactlyt he same as A.g()
}
}
/// One more class
class C: B
{
/// $(INHERIT_ALL)
public override void f(int x)
{
// documentation will be exactlyt he same as B.f()
}
/**
* Some other doc
*/
public override bool f()
{
// nothing inherited.
}
}
---
Comment #2 by andrej.mitrovich — 2013-06-18T06:38:59Z
See also Issue 7688.
Comment #3 by leandro.lucarella — 2013-06-18T07:39:33Z
(In reply to comment #2)
> See also Issue 7688.
7688 is a nice, but completely different issue :)
Comment #4 by leandro.lucarella — 2013-06-18T07:43:10Z
(In reply to comment #1)
> vibe.d has introduced ddox https://github.com/rejectedsoftware/ddox
>
> It does much of what almost everyone has asked for, including this (I think).
> I believe there is a pull request to make dlang.org able to use it:
>
> https://github.com/D-Programming-Language/dlang.org/pull/267
>
> See the result:
>
> http://vibed.org/temp/d-programming-language.org/phobos/std/stream/FilterStream.html
I knew about ddox, but I think it just inherit the whole documentation, it doesn't allow inheriting only parts. I think the approach I suggest here is more flexible and I have the feeling it wouldn't be too hard to implement, what you need to do is just define a new macro and make it expand to the particular sections of parent class documentation.
Comment #5 by doob — 2013-06-18T13:39:57Z
I would really like to have this. But I think I would like to inherit the all the documentation automatically.
Comment #6 by robert.schadek — 2024-12-13T18:08:22Z