In std.compiler there is this code:

    /// Which vendor produced this compiler.
    version(StdDdoc)          Vendor vendor;
    else version(DigitalMars) Vendor vendor = Vendor.digitalMars;
    else version(GNU)         Vendor vendor = Vendor.gnu;
    else version(LDC)         Vendor vendor = Vendor.llvm;
    else version(D_NET)       Vendor vendor = Vendor.dotNET;
    else version(SDC)         Vendor vendor = Vendor.sdc;
    else                      Vendor vendor = Vendor.unknown;

What is the situation in which the identifier StdDoc is set?

On Friday, 23 November 2018 at 21:47:51 UTC, Tony wrote:
> What is the situation in which the identifier StdDoc is set?

When the phobos website is being compiled, its own makefile sets that.

It is basically a hack for website display.

On Fri, Nov 23, 2018 at 09:53:59PM +0000, Adam D. Ruppe via Digitalmars-d-learn wrote:
> On Friday, 23 November 2018 at 21:47:51 UTC, Tony wrote:
> > What is the situation in which the identifier StdDoc is set?
> 
> When the phobos website is being compiled, its own makefile sets that.
> 
> It is basically a hack for website display.

Yes, it's a hack to make the website display something different from what ddoc would actually generate from the real code.

There are a few cases where this is needed, e.g., to generate docs for Windows-specific modules, since the website script is run on Posix and the Windows APIs would not be compiled at all, leading to empty docs.


T

-- 
It's amazing how careful choice of punctuation can leave you hanging:

On Friday, 23 November 2018 at 23:13:04 UTC, H. S. Teoh wrote:
> There are a few cases where this is needed, e.g., to generate docs for Windows-specific modules, since the website script is run on Posix and the Windows APIs would not be compiled at all, leading to empty docs.

Note that that is only because ddoc is a badly designed piece of garbage. Good doc generators can handle that just fine.

On Sat, Nov 24, 2018 at 12:51:36AM +0000, Adam D. Ruppe via Digitalmars-d-learn wrote:
> On Friday, 23 November 2018 at 23:13:04 UTC, H. S. Teoh wrote:
> > There are a few cases where this is needed, e.g., to generate docs for Windows-specific modules, since the website script is run on Posix and the Windows APIs would not be compiled at all, leading to empty docs.
> 
> Note that that is only because ddoc is a badly designed piece of garbage.  Good doc generators can handle that just fine.

Ddoc may have its stink points, but in this case, the stuff inside version(Windows) blocks simply isn't compiled, so you can't expect ddoc to do much about it.  You can't just arbitrarily ddoc everything inside version blocks, because then you'll end up with ddocs for stuff inside version(none) and/or conflicting docs for alternative declarations in, say, OS-specific version blocks, or user-defined static if's.

Having said that, though, it would be nice if there was a way to tell the compiler "please generate docs for Windows, even though you're currently running on Posix".  Resorting to hacks like that just to generate Phobos docs simply sux.


T

-- 
Notwithstanding the eloquent discontent that you have just respectfully expressed at length against my verbal capabilities, I am afraid that I must unfortunately bring it to your attention that I am, in fact, NOT verbose.

On Saturday, 24 November 2018 at 01:21:25 UTC, H. S. Teoh wrote:
> Ddoc may have its stink points, but in this case, the stuff inside version(Windows) blocks simply isn't compiled

That is why I call it "poorly designed" and a major reason why I dropped it entirely and created my own doc generator from scratch (well, using libdparse, so not exactly scratch, but zero use of dmd's code).

> You can't just arbitrarily ddoc everything inside version blocks, because then you'll end up with ddocs for stuff inside version(none) and/or conflicting docs for alternative declarations in, say, OS-specific version blocks, or user-defined static if's.

That is easy to handle, you just treat it like overloads and display the version info along with the rest of it if both are documented. My doc generator does this and it is very useful - you can show what are under special version specifiers, call out OS differences, and more.

And if there are conflicting docs, the user ought to be able to see that!

On Fri, 23 Nov 2018 17:21:25 -0800, H. S. Teoh wrote:
> Ddoc may have its stink points, but in this case, the stuff inside version(Windows) blocks simply isn't compiled, so you can't expect ddoc to do much about it.  You can't just arbitrarily ddoc everything inside version blocks, because then you'll end up with ddocs for stuff inside version(none) and/or conflicting docs for alternative declarations in, say, OS-specific version blocks, or user-defined static if's.

That means that, instead of one site showing my project's documentation, I need a separate site for every combination of platform and version flags. And users who care about differences between platforms and version flags need to manually cross-reference docs for every symbol and overload.

It's a pretty terrible status quo.

On Sat, Nov 24, 2018 at 02:09:22AM +0000, Neia Neutuladh via Digitalmars-d-learn wrote:
> On Fri, 23 Nov 2018 17:21:25 -0800, H. S. Teoh wrote:
> > Ddoc may have its stink points, but in this case, the stuff inside version(Windows) blocks simply isn't compiled, so you can't expect ddoc to do much about it.  You can't just arbitrarily ddoc everything inside version blocks, because then you'll end up with ddocs for stuff inside version(none) and/or conflicting docs for alternative declarations in, say, OS-specific version blocks, or user-defined static if's.
> 
> That means that, instead of one site showing my project's documentation, I need a separate site for every combination of platform and version flags.  And users who care about differences between platforms and version flags need to manually cross-reference docs for every symbol and overload.
> 
> It's a pretty terrible status quo.

True.  I've tried to tackle this before, but conceded defeat after I realized that dmd just can't handle it because of the way ddoc is implemented.

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.

Now that I think about this more carefully, I feel tempted to say that we should write a standalone ddoc generator, or at least a standalone module in dmd, that process *all* source code regardless of version blocks and static ifs and what-not. The output should be properly tagged (e.g., the path of version identifiers / static if conditions that lead to a particular version of the doc) so that the formatting backend can render it sensibly, e.g., as a HTML drop-down list of versions, or whatever.

But then that would be reinventing what Adam has already done, right? :-D


T

-- 
If I were two-faced, would I be wearing this one? -- Abraham Lincoln

On Saturday, 24 November 2018 at 02:55:04 UTC, H. S. Teoh wrote:
> But then that would be reinventing what Adam has already done, right? :-D

Precisely, I already do all that. And people are even actually using it!

On Friday, November 23, 2018 2:47:51 PM MST Tony via Digitalmars-d-learn wrote:
> In std.compiler there is this code:
>
>      /// Which vendor produced this compiler.
>      version(StdDdoc)          Vendor vendor;
>      else version(DigitalMars) Vendor vendor = Vendor.digitalMars;
>      else version(GNU)         Vendor vendor = Vendor.gnu;
>      else version(LDC)         Vendor vendor = Vendor.llvm;
>      else version(D_NET)       Vendor vendor = Vendor.dotNET;
>      else version(SDC)         Vendor vendor = Vendor.sdc;
>      else                      Vendor vendor = Vendor.unknown;
>
> What is the situation in which the identifier StdDoc is set?

It's a Phobos-only replacement for the D_Ddoc version identifier and is defined as part of the Phobos build. As the others have been complaining about in this thread, ddoc is set up so that it takes whatever version is currently being compiled. So, version(D_Ddoc) is the standard way to provide documentation that is agnostic of the platform in the cases where a documented symbol doesn't exist on all platforms, or its definition differs such that it needs separate declarations - e.g. if the values of members in an enum differ across systems, then you're forced to provide completely separate enum declarations for the entire enum. If you have separate declarations on different platforms, then in general there are only three choices

1. Duplicate the documentation.

2. Set it up so that your documentation can only be built on one platform.

3. Use version(D_Ddoc) to provide a separate declaration just for the
documentation.

There are some cases where you can put the documentation outside the version block and have it work - e.g.

/// my documentation
version(linux) int foo(string bar) { ... }
else version(Windows) int foo(string bar) { ... }
else ...

but that only works when you only need to document the top-level symbol (such as with a function). It does not work with anything that needs to have symbols inside it documented (such as with a struct, class, or enum).

Fortunately, most code does need to be versioned like this (especially if you're trying to write platform-independent code like we try to do with Phobos), and often, when you do need to version stuff, it's inside implementations, but sometimes it does affect the top level. std.file has this problem in a few places as does std.datetime with WindowsTimeZone (since it only exists on Windows). The solution the language provides is to use version(D_Ddoc) to version such documentation. And that's what Phobos used to do.

The problem is that once you start using version(D_Ddoc), you _must_ have a separate documentation build. You can't build your documentation as part of your normal build, because you'd be getting the version(D_Ddoc) stubs instead of the correct implementation for your platform (or instead of nothing at all if that platform isn't supposed to have that particular symbol). Phobos already had a separate documentation build because of how it generates the documentation for the website, but many people's projects do not. Most projects don't ever need to use version(D_Ddoc), because they don't have symbols that are platform-dependent, and so before Phobos started using it, they could compile their documentation as part of their normal build just fine, because version(D_Ddoc) wasn't in their code anywhere. But as soon as Phobos started using it, their code broke. If they had had a separate documentation build, then they wouldn't have had any problems, but as it was, their code was broken.

So, for better or worse, rather than saying that it was just bad practice to do the documentation build as part of your normal build (and I would strongly argue that building the documentation as part of the normal build is bad practice given how doing so defines a new version identifier that can affect the build), it was decided that Phobos would stop using version(D_Ddoc) as the language intended and instead use its own custom, version identifier for the documentation - which is why we now have version(StdDoc) in Phobos and version(CoreDdoc) in druntime. With this change, anyone building with the -D flag as part of their normal build doesn't end up with version(D_Ddoc) screwing up their code because of druntime or Phobos. Some other project they depend on could screw it up, and if they ever use version(D_Ddoc) in their code, they'll have trouble again, but Phobos and druntime aren't going to mess them up in that regard.

And while version(D_Ddoc) is the standard solution, because of this general problem with folks using -D with their normal build, it's arguably best practice at this point to create your own version identifier for your own documentation for any library that you release that needs to version its documentation. Otherwise, anyone using your library will have the same problems that resulted in Phobos switching from version(D_Ddoc) to version(StdDdoc) - which if anything shows that things work here probably should have been handled differently.

Really, the way that -D is designed is similar to -unittest in that they're both intended to be used for builds other than your normal build. They create their own version identifiers and can change how the code compiles. And as such really should not be used as part of the normal build. But just like -unittest runs the unit tests by making them run before main, thus making it so that you can technically have the unit tests be part of your normal build (even if it's unwise), you can have the documentation as part of your normal build (even if it's unwise). Arguably, just like the complaints that Adam Ruppe and H.S. Teoh are making elsewhere in the thread, this aspect of how the compiler and language are designed to work is not the best designed. It works just fine if you understand the pitfalls, but having the unit tests and documentation treated in such a way that they can be part of the normal build instead of always replacing the normal build definitely is an area that sometimes causes problems for people.

- Jonathan M Davis