On Wednesday, 1 April 2020 at 14:15:36 UTC, Steven Schveighoffer wrote:
>
> Any idea on when these will become permanent or be removed? We are collecting quite a few of these. Which means, we are currently shipping 2^11 different compilers simultaneously (I know there's really less since some of them activate the others).

And your list is missing `-preview=in` which is not part of a release yet.
When will they be enabled ? When someone does the work to actually finish them.
I've never been a fan of the `-preview` switch, simply because it tends to lead to feature which are incomplete.

DIP1008 didn't work for the first year or so, and has issues at the moment with safety IIRC. rvalueref is plain broken (doesn't work with template inference).
DIP25 will actually be on by default on the next release. This led to a pretty long discussion which you might be interested in: https://github.com/dlang/dmd/pull/10805

Personally I have an interest in seeing rvalueref, nosharedaccess, and perhaps dip1008, so that's what I'm going to be pushing for in the next few months whenever I get time.

On 4/1/20 1:31 PM, Mathias LANG wrote:
> On Wednesday, 1 April 2020 at 17:12:00 UTC, David Gileadi wrote:
>>
>> Yes, it's that last thing--I'm exclusively on a Mac. I guess I could set up a VM in VirtualBox or something but so far I've been too lazy/distracted to make the time for it.
> 
> The way the documentation generator works at the moment is less than ideal. If doesn't really take into account `static if`, `version`, etc... The solution needs to be at the DMD level, not at the project level.

I don't know how to fix this. Basically, if you don't want to build the whole project as it is on each platform, you need to have special ddoc versions for things. In this case, you have enum definitions that are not defined on the platform that D builds its docs. So whoever did this replicated the entire file but just without any actual definitions, and tagged them for ddoc. I think this was the wrong approach, we should have tagged them and included the real definitions if version(CoreDdoc) was true.

I've seen a few "workarounds" for generating documentable code for multiple platforms, or for projects that include other libraries but don't want to build those other libraries just for ddoc.

An example of the latter is mysql-native, which defines stubs for vibe-d items for documentation, since vibe-d is optional.

I wonder if the way to build the documentation is simply to build it with all possible platform definitions, and section them off. The html could have a platform selector or something that allows you to see what your platform or configuration supports.

Something like a switch to dmd like:

-ddoc-config=OSX -ddoc-config=Linux ddoc-config=Linux,Have_Vibed

And then it generates all the docs for all those configurations based on trying each of those versions on the AST.

-Steve

On 4/1/20 1:12 PM, David Gileadi wrote:
> Yes, it's that last thing--I'm exclusively on a Mac.

Well in that case, let's just see what happens ;)

https://github.com/dlang/druntime/pull/3016

-Steve

On Wednesday, 1 April 2020 at 17:51:47 UTC, Steven Schveighoffer wrote:
>> The way the documentation generator works at the moment is less than ideal.
>
> I don't know how to fix this.

This is why I abandoned the approach of using dmd entirely and wrote a separate doc generator with a separate parser.

Then it is able to display version things like here:

http://dpldocs.info/experimental-docs/arsd.simpledisplay.PosixFdReader.html

vs

http://dpldocs.info/experimental-docs/arsd.simpledisplay.WindowsHandleReader.html

It just plain tells you it is `version(Windows) class WindowsHandleReader`.

On Wednesday, 1 April 2020 at 14:15:36 UTC, Steven Schveighoffer wrote:
> dmd '-preview=?'
>
> Upcoming language changes listed by -preview=name:
>   =all              list information on all upcoming language changes
>   =dip25            implement https://github.com/dlang/DIPs/blob/master/DIPs/archive/DIP25.md (Sealed references)
>   =dip1000          implement https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1000.md (Scoped Pointers)
>   =dip1008          implement https://github.com/dlang/DIPs/blob/master/DIPs/other/DIP1008.md (@nogc Throwable)
>   =dip1021          implement https://github.com/dlang/DIPs/blob/master/DIPs/accepted/DIP1021.md (Mutable function arguments)
>   =fieldwise        use fieldwise comparisons for struct equality
>   =markdown         enable Markdown replacements in Ddoc
>   =fixAliasThis     when a symbol is resolved, check alias this scope before going to upper scopes
>   =intpromote       fix integral promotions for unary + - ~ operators
>   =dtorfields       destruct fields of partially constructed objects
>   =rvaluerefparam   enable rvalue arguments to ref parameters
>   =nosharedaccess   disable access to shared memory objects
>
>[snip]

It would probably be good if there were a spec page for these...I remember seeing them in the Changelog, but I completely even forgot that fixAliasThis was a thing. It would also be an opportunity to get the additional documentation that will need to be added to the spec ready in advance.

On Wednesday, 1 April 2020 at 18:04:01 UTC, Adam D. Ruppe wrote:
> This is why I abandoned the approach of using dmd entirely and wrote a separate doc generator with a separate parser.

Also note:

http://dpldocs.info/experimental-docs/arsd.simpledisplay.GlobalHotkey.html

Trying to do that by different builds... how would you know to do custom version specifiers? What about `static if` conditions? Just showing it is the only sane way I can imagine.

On 4/1/20 2:12 PM, Adam D. Ruppe wrote:
> On Wednesday, 1 April 2020 at 18:04:01 UTC, Adam D. Ruppe wrote:
>> This is why I abandoned the approach of using dmd entirely and wrote a separate doc generator with a separate parser.
> 
> Also note:
> 
> http://dpldocs.info/experimental-docs/arsd.simpledisplay.GlobalHotkey.html
> 
> Trying to do that by different builds... how would you know to do custom version specifiers? What about `static if` conditions? Just showing it is the only sane way I can imagine.

It looks good. I have a question though.

What about when you have things like this:

version(OSX) version = someFunkyVersion;
version(Linux) version = someFunkyVersion;

///
version(someFunkyVersion) void documentMe();

does that display "someFunkyVersion" or version(OSX || Linux) or something like that?

Because the incorrect thing to imply is that you have to define the version it's saying.

A feature I'd like to see too (but please don't do it for just me, as I don't use your docs at the moment), is to have version filters at the top so you can see docs only relevant to your platform. Should be pretty simple JS addition.

-Steve

On Wednesday, 1 April 2020 at 18:21:46 UTC, Steven Schveighoffer wrote:
> What about when you have things like this:
>
> version(OSX) version = someFunkyVersion;
> version(Linux) version = someFunkyVersion;
>
> ///
> version(someFunkyVersion) void documentMe();
>
> does that display "someFunkyVersion" or version(OSX || Linux) or something like that?

It'll say "someFunkyVersion", it keeps what's in the source. (that link there actually does just that - version(X11) is defined above as the default on version(linux)).

What I haven't done yet is auto-link those identifiers back to the original definition, so you can actually see it and any attached ddoc comment. But even without that, actually seeing what's in the source works a lot better than just skipping it entirely in the docs!

> A feature I'd like to see too (but please don't do it for just me, as I don't use your docs at the moment), is to have version filters at the top so you can see docs only relevant to your platform. Should be pretty simple JS addition.

Oh perhaps, but given how complicated some of the this can be. Like does a filter on `someFunkyVersion` include OSX? Does one on OSX include it?

It is certainly possible, the language's feature-poor `version` thing is actually a kinda nice benefit here since it isn't too hard to recreate that logic and rebuild the chain in a doc script too.

But it is just all more than it looks at first glance.

On Wed, Apr 01, 2020 at 06:12:39PM +0000, Adam D. Ruppe via Digitalmars-d wrote:
> On Wednesday, 1 April 2020 at 18:04:01 UTC, Adam D. Ruppe wrote:
> > This is why I abandoned the approach of using dmd entirely and wrote a separate doc generator with a separate parser.
> 
> Also note:
> 
> http://dpldocs.info/experimental-docs/arsd.simpledisplay.GlobalHotkey.html
> 
> Trying to do that by different builds... how would you know to do custom version specifiers? What about `static if` conditions? Just showing it is the only sane way I can imagine.

Yeah, the problem with ddoc is that it's tied to what the compiler actually compiles, so things like version() and static if throw it off because the compiler prunes entire branches from the AST before processing it.

When generating docs, in theory *all* ddoc comments should emit output, and each conditional branch should add to a list of clauses attached to the ddoc output.  I doubt this is feasible to implement in the current dmd code, though.


T

-- 
Why are you blatanly misspelling "blatant"? -- Branden Robinson

On 4/1/20 2:32 PM, Adam D. Ruppe wrote:
> On Wednesday, 1 April 2020 at 18:21:46 UTC, Steven Schveighoffer wrote:
>> What about when you have things like this:
>>
>> version(OSX) version = someFunkyVersion;
>> version(Linux) version = someFunkyVersion;
>>
>> ///
>> version(someFunkyVersion) void documentMe();
>>
>> does that display "someFunkyVersion" or version(OSX || Linux) or something like that?
> 
> It'll say "someFunkyVersion", it keeps what's in the source. (that link there actually does just that - version(X11) is defined above as the default on version(linux)).

Yeah, I suppose that's still more useful than nothing.

>> A feature I'd like to see too (but please don't do it for just me, as I don't use your docs at the moment), is to have version filters at the top so you can see docs only relevant to your platform. Should be pretty simple JS addition.
> 
> Oh perhaps, but given how complicated some of the this can be. Like does a filter on `someFunkyVersion` include OSX? Does one on OSX include it?
> 
> It is certainly possible, the language's feature-poor `version` thing is actually a kinda nice benefit here since it isn't too hard to recreate that logic and rebuild the chain in a doc script too.

My expectation is that you would provide the list of versions to "turn on or off", and then use that data to determine when symbols are present. These would probably just be the OS versions I would think. Semantic processing on the version statements should be pretty straightforward since they are so limited.

-Steve