Another use case for __traits(docComment)

Dennis dkorpel at
Thu Nov 14 20:24:46 UTC 2019

On Thursday, 14 November 2019 at 17:18:40 UTC, Jab wrote:
> Should we have not added extern(C++, identifier) to D to begin 
> with?

> Should they have not been given that feature because down the 
> line there's going to be numerous bugs with it that will need 
> to be fixed and people will then be wanting more and more 
> changes to it?

I haven't interfaced with C++ so I can't judge that, but from a 
spectator of the discussion point of view `extern(C++, "ns")` 
seemed like a worthy addition.
I only brought this up as an example to show how these things 
don't end with "just this one small addition" like Adam makes it 
out to be in the case of __traits(docComment).

> Was kind of curious what that looks like with a comment from 
> phobos, I think it's worse than I expected.

So I wouldn't use that for Phobos, but export Phobos 
documentation to a preferred file format and use that. What would 
you do with the raw ddoc comment anyway, print it in the terminal 
as-is with $() and all? Re-implement macro parsing in CTFE?

The UDA duplication is acceptable when you are writing some small 
comments yourself:

struct WindowSettings
     @("The default width of the window in pixels.")
     int width = 1280; /// default window width in pixels

     @("The default height of the window in pixels.")
     int height = 720; /// default window height in pixels

If you want to make a GUI for setting the width and height based 
on the struct then you want to poll the UDA string to get a nice 
description for the user.
And I know it is tempting to want to combine the two, based on 
the availability of __traits(docComment):

struct WindowSettings
     int width = 1280; /// The default width of the window in 
     int height = 720; /// The default height of the window in 

But before you know it you deal with all kinds of issues, like 
the user-facing comment and the programmer-facing comment 
diverging, needing to strip the leading space, the formatter 
changing it to a multi-line comment introducing other whitespace, 
wanting to the comment to be generated at CTFE so you have to 
turn back to UDA's anyway etc.

And it may just turn out that simple > clever all along.

More information about the Digitalmars-d mailing list