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

           Summary: Ddoc ignores methods in static else block
           Product: D
           Version: D2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: DMD
        AssignedTo: nobody@puremagic.com
        ReportedBy: joseph.wakeling@webdrake.net


--- Comment #0 from Joseph Rushton Wakeling <joseph.wakeling@webdrake.net> 2013-10-24 02:03:14 PDT ---
Created an attachment (id=1283)
Example code illustrating the bug: ddoc entry in a static else block is not
used

In the event that a static if {} else {} block is used to determine what methods belong to a struct/class, Ddoc will ignore the documentation for methods defined in the if {} block.

The attached code shows 2 different classes: one where two different functions
are defined depending on a static if/else block, another where the same effect
is achieved with two static if blocks (static if (cond) { ... } static if
(!cond) { ... }).

In the first case, the second function is not picked up by ddoc; in the second, it is.

-- 
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=11337



--- Comment #1 from Joseph Rushton Wakeling <joseph.wakeling@webdrake.net> 2013-10-24 02:13:38 PDT ---
N.B. as an ideal case, it should be possible to use /// ditto comments in the else {} block, and have them pick up on whatever methods precede them.

-- 
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=11337


Jonathan M Davis <jmdavisProg@gmx.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |jmdavisProg@gmx.com


--- Comment #2 from Jonathan M Davis <jmdavisProg@gmx.com> 2013-10-24 03:48:30 PDT ---
If anything, I would say that the fact that Coin2 shows both is the problem rather than the fact that Coin1 shows only one. In neither case can both exist, and normally, ddoc only shows the code that gets compiled in (e.g. versioned out code will not show up in the generated documentation). Normally, when you get something weird like this, you use version(D_Ddoc) blocks to make the documentation show what you want, but it's not particularly correct for it to blindly throw everything for all of the various static if branches into the documentation. The result wouldn't look anything like the actual class.

I think that it's getting a bit weird here because while the compiler normally doesn't show stuff in the documentation that isn't compiled in, it tries to show templated stuff even if it's not compiled in. And because it's then generating documentation for a template which isn't associated with a particular instantiation, it doesn't actually know what is and isn't supposed to be compiled in. If those static ifs were outside of a template, then only the branches which were true would end up with the documentation being generated for them. So, the template just makes things weird. It also makes it much harder to even know what the correct thing to do with the documentation is, because what the documentation should look like could depend on the template arguments (as is the case here).

-- 
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=11337



--- Comment #3 from Joseph Rushton Wakeling <joseph.wakeling@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: -------