version(StdDoc)

[Adam D. Ruppe]

On Saturday, 24 November 2018 at 16:16:08 UTC, H. S. Teoh wrote:
> Actually, what would be ideal is if each platform-specific 
> version of the symbol can have its own associated 
> platform-specific docs, in addition to the one common across 
> all platforms, and the doc system would automatically compile 
> these docs into a single block in the output, possibly by 
> introducing platform specific sections, e.g.:

Well, I probably could do that, but I'm not so sure it would make 
since since it separates stuff quite a bit and may have weird 
cases. Like what if the arguments are different? Should it merge 
the params sections? (That is doable btw)

But also from the user side, when they are looking for 
differences, it is a pain if most the stuff is shared and there 
is just a different sentence at the bottom or something. I'd 
prolly insist that it be called out. Of course, the doc gen could 
automatically merge the docs with headers too... but that brings 
us to something we already have:

I just use...

/++
     Does whatever.

     Note on Windows it does something a bit different.
+/
version(linux)
void foo();

/// ditto
version(Windows)
void foo();


So the ditto covers the case and tells the doc gen they share the 
same stuff, and the header is written however we want in the 
comment.

I don't *hate* having shared docs on version blocks, I am just 
being lazy and avoiding implementation by pushing back :P


(Though a parsing thing: /// version(linux) void foo(); - is that 
doc on version linux or on void foo or on both? I guess it could 
only apply it in if there are {}... but eh I still don't love it.)



> It's a bad thing to separate the docs from the actual code, 
> because then the two are liable to go out-of-sync with each 
> other.

that depends on what kind of docs. for api reference, sure, but 
other docs prolly should be separate because they are bigger 
picture, and thus don't naturally fit well in with the code.


But of course, version(D_Ddoc) is the worst of both worlds.