Today I happened to have a bit of free time, and trawled through some of the old bugs I filed on bugzilla.  Came across this one:

	https://issues.dlang.org/show_bug.cgi?id=14972

The basic problem is that Windows functions are only available on Windows, and therefore they are inside a version(Windows) block, but the machine used to generate the docs runs on Posix, so all these functions will be version'd out.  So std.windows.registry, for example, is a blank page on dlang.org:

	https://dlang.org/phobos/std_windows_registry.html

This got me thinking, though: since LDC now comes prebuilt with Windows target (among many others), what don't we use LDC to generate these platform-specific docs?  Just run it `ldc2 -mtriple=x86_64-windows-msvc` to generate the docs, and it will pick up all the Windows-specific functions with no need for stupid hacks like version(Ddoc) that's used in some places in Phobos.  No need for complicated setting up of a Windows CI machine for generating docs, etc..

(The version(Ddoc) hack is stupid because it's basically inserting a fake function declaration alongside the real one that may or may not match the latter: the two are liable to go out of sync and nobody would know any better until some hapless user runs into the discrepancy.)


T

-- 
I am a consultant. My job is to make your job redundant. -- Mr Tom

On Tuesday, 10 December 2019 at 19:02:23 UTC, H. S. Teoh wrote:
> [snip]

I thought the longer-term solution was to make the compiler aware of comments inside version blocks when compiled with -D.

On Tuesday, 10 December 2019 at 19:33:56 UTC, jmh530 wrote:
> I thought the longer-term solution was to make the compiler aware of comments inside version blocks when compiled with -D.

or just use my adrdox which has handled this correctly for years now.

http://dpldocs.info/experimental-docs/std.windows.registry.html