[Issue 10399] New: ddoc: Add a way to inherit documentation from the parent class

[d-bugmail at puremagic.com]

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 at puremagic.com
        ReportedBy: leandro.lucarella at sociomantic.com


--- Comment #0 from Leandro Lucarella <leandro.lucarella at 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: -------