On Friday, November 23, 2018 7:55:04 PM MST H. S. Teoh via Digitalmars-d- learn wrote: > Adam does have a very good point about showing all alternatives to docs, > though. Arguably, that's what ddoc *should* do. If the programmer > wrote a ddoc comment in the code, it probably should be processed as > part of doc generation, regardless of whether that code sits in some > deeply-nested version blocks that ends up not being compiled. Binding > ddoc generation to the compile process seems not such a good idea in > retrospect.
Honestly, I would argue that if you have multiple versions of the documentation, then there's a serious problem. The documentation shouldn't be platform-dependent even if the symbols are. Even if the documentation needs some extra notes for a specific platform, it should all be in one documentation block that anyone using the symbol can read. Providing different documentation for different platforms just leads to folks not understanding how the symbol differs across platforms, leading to code that is even more platform-dependent when it really should be as platform independent as possible. The only situation I can think of at the moment where anything along the lines of combining documentation across platforms makes sense would be if there is a nested symbol that exists on only one platform (e.g. a member function of a struct or a member of an enum). In that case, one platform would have the main documentation, and then system-specific symbols would be documented in those version blocks - but only those symbols. A solution like that might work reasonably well, but you still have the problem of what to do when a symbol is documented in multiple version blocks, and having almost all the documentation in one version block and a few pieces of it in other version blocks would risk getting confusing and messy. As such, I'm not sure that the fact that ddoc forces you to have a separate set of declarations just for the documentation is really a bad thing. It puts all of the documentation in one place. The bigger problem IMHO is how -D affects the build. Both it and -unittest have the fundamental problem that because they create their own version identifiers, they really shouldn't be part of the normal build, and yet the way that they're set up to be used, it's as if they're expected to be part of the normal build - with -D just causing the compiler to generate the documentation in addition to the binary, and -unittest making the unit tests run before main rather than replacing main. At this point, I really wish that at minimum, -D were not set up to be part of the normal build process so that version(D_Ddoc) would not affect it. The same with -unittest. Ideally, it really would have replaced main rather than putting the unit tests before it, with it providing main if one wasn't there. That still doesn't solve all of the problems when using version(unittest), but I doubt that much of anyone really wants to be running unit tests as part of their application, and having such flags clearly designed to create special builds rather than being designed such that they could be used with the normal build would have fixed certain classes of problems. As for the issue of versioning the documentation, I don't really see a clean one. Having the documentation build affected by version and static if and the like causes some problems, but having it ignore them would likely cause other problems. Regardless, I suspect that having the version identifiers and static ifs be ignored almost requires a separate tool from the compiler (such as Adam's documentation generator or ddox), because it's pretty clear that ddoc was set up to generate the documentation for symbols as the compiler compiles them, whereas a tool that ignored version identifiers and static ifs would be processing the file quite differently. - Jonathan M Davis
