• H. S. Teoh (23/23) Dec 10 2019 Today I happened to have a bit of free time, and trawled through some of
• jmh530 (3/4) Dec 10 2019 I thought the longer-term solution was to make the compiler aware
• Adam D. Ruppe (4/6) Dec 10 2019 or just use my adrdox which has handled this correctly for years

"H. S. Teoh" <hsteoh quickfur.ath.cx> writes:

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

jmh530 <john.michael.hall gmail.com> writes:

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.

Adam D. Ruppe <destructionator gmail.com> writes:

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