Ddoc ignores methods in static else block

[dlangBugzillaToGithub]

Joseph Rushton Wakeling (@WebDrake) reported this on 2013-10-24T02:03:14Z

Transferred from https://issues.dlang.org/show_bug.cgi?id=11337

CC List

• Jonathan M Davis (@jmdavis)
• Nick Treleaven (@ntrel)

Description

Created attachment 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.

!!!There are attachements in the bugzilla issue that have not been copied over!!!

[dlangBugzillaToGithub]

joseph.wakeling commented on 2013-10-24T02:13:38Z

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.

[dlangBugzillaToGithub]

issues.dlang (@jmdavis) commented on 2013-10-24T03:48:30Z

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).

[dlangBugzillaToGithub]

joseph.wakeling commented on 2013-10-24T07:30:05Z

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.

[dlangBugzillaToGithub]

hsteoh commented on 2020-07-13T19:25:22Z

A related problem is blocks that are version()'d out. I think this represents a fundamental weakness of ddoc, in that it only sees code that's actually compiled, not code that's *potentially* compiled.

There is no easy solution either; for example, the source code may contain version(none) or static if(0) blocks containing non-compilable code; you probably don't want to generate docs for that!  But you can't just check the condition for 'none' or '0' because the actual condition may be more complex than that.

A potential workaround might be some kind of in-source ddoc directive to tell ddoc to generate docs for blocks that otherwise would not be compiled, say something like:

------
/// ddoc:force-gen
static if (myCond) {
    /// Ddocs
    auto stuff(...) { ... }
} else {
    /// more ddocs
    auto otherStuff(...) { ... }
}
------

The ddoc generator would recognize the `ddoc:force-gen` directive and generate docs for both branches of the static if, where otherwise it would only generate one.

Just throwing the idea out there to see if it sticks.

[dlangBugzillaToGithub]

nick (@ntrel) commented on 2022-10-09T17:00:28Z

> A related problem is blocks that are version()'d out. 
> I think this represents a fundamental weakness of ddoc, in that it only sees 
> code that's actually compiled, not code that's *potentially* compiled

ddoc doesn't work like that for `version`, see issue 21400.