[Issue 11337] Ddoc ignores methods in static else block

[d-bugmail at puremagic.com]

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



--- Comment #3 from Joseph Rushton Wakeling <joseph.wakeling at webdrake.net> 2013-10-24 07:30:05 PDT ---
Hmm, I appreciate what you're saying but for me it's logical that you should be
able to document templated code in complete fashion, i.e. that you should be
able to document every possible member function and that it should be clear
what will occur under which circumstances.  I don't see how else one could
reliably generate documentation for a Boost-style "header-esque" library.

The particular motivation for me is this:
https://github.com/WebDrake/Dgraph/blob/141c8e2cd40376be2237b7d0bee6d73af75fbc0e/source/dgraph/graph.d#L253-L290

... where I have different functions defined in a class depending on a template
parameter, but where I'd like them all to be documented.  I'm happy for
suggestions as to how to alternatively do that, but it just seems a bit odd
that if stuff inside any kind of static if is displayed _at all_ without
explicit instantiation, that stuff inside the "if" is displayed but not stuff
from the "else".

Note that another way to define Coin would be something like,

    /// Yet another coin
    struct Coin3(bool heads)
    {
        /// Coin shows heads
        void head()()
        if (heads)
        {
        }

        /// Coin shows tails
        void tail()()
        if (!heads)
        {
        }
    }

... which documents both functions, but also includes the template if
constraint.  Could ddoc be re-worked to do something similar for stuff inside a
static if/else?

The problem with this 3rd approach is that it makes head and tail both part of
the public API, regardless of the underlying boolean value of heads; it's
_calling_ one of them that will fail.

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