Bug 11337 – Ddoc ignores methods in static else block

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.

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.

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

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.

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.

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

THIS ISSUE HAS BEEN MOVED TO GITHUB https://github.com/dlang/dmd/issues/18703 DO NOT COMMENT HERE ANYMORE, NOBODY WILL SEE IT, THIS ISSUE HAS BEEN MOVED TO GITHUB