www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 11337] New: Ddoc ignores methods in static else block

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



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




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


Jonathan M Davis <jmdavisProg gmx.com> changed:

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



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




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: -------
Oct 24 2013