www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 10399] New: ddoc: Add a way to inherit documentation from the parent class

reply d-bugmail puremagic.com writes:
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



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: -------
Jun 18 2013
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=10399


Steven Schveighoffer <schveiguy yahoo.com> changed:

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



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: -------
Jun 18 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
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



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: -------
Jun 18 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=10399




2013-06-18 07:39:33 PDT ---


 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: -------
Jun 18 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=10399




2013-06-18 07:43:10 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


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: -------
Jun 18 2013
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=10399


Jacob Carlborg <doob me.com> changed:

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



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: -------
Jun 18 2013