http://d.puremagic.com/issues/show_bug.cgi?id=10399

           Summary: ddoc: Add a way to inherit documentation from the
                    parent class
           Product: D
           Version: D1 & D2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: enhancement
          Priority: P2
         Component: DMD
        AssignedTo: nobody@puremagic.com
        ReportedBy: leandro.lucarella@sociomantic.com


--- Comment #0 from Leandro Lucarella <leandro.lucarella@sociomantic.com> 2013-06-18 04:18:33 PDT ---
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.
    }
}

---

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=10399


Steven Schveighoffer <schveiguy@yahoo.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |schveiguy@yahoo.com


--- Comment #1 from Steven Schveighoffer <schveiguy@yahoo.com> 2013-06-18 06:36:25 PDT ---
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

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=10399


Andrej Mitrovic <andrej.mitrovich@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |andrej.mitrovich@gmail.com
           See Also|                            |http://d.puremagic.com/issu
                   |                            |es/show_bug.cgi?id=7688


--- Comment #2 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2013-06-18 06:38:59 PDT ---
See also Issue 7688.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=10399



--- Comment #3 from Leandro Lucarella <leandro.lucarella@sociomantic.com> 2013-06-18 07:39:33 PDT ---
(In reply to comment #2)
> See also Issue 7688.

7688 is a nice, but completely different issue :)

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=10399



--- Comment #4 from Leandro Lucarella <leandro.lucarella@sociomantic.com> 2013-06-18 07:43:10 PDT ---
(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.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------

http://d.puremagic.com/issues/show_bug.cgi?id=10399


Jacob Carlborg <doob@me.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |doob@me.com


--- Comment #5 from Jacob Carlborg <doob@me.com> 2013-06-18 13:39:57 PDT ---
I would really like to have this. But I think I would like to inherit the all the documentation automatically.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------