Another use case for __traits(docComment)

[Jab]

On Thursday, 14 November 2019 at 20:24:46 UTC, Dennis wrote:
> 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).

For him it probably would be, but there's numerous people out 
there that want something else. There's always going to be 
something people will want to improve on. I don't think that's a 
good enough reason to not do something. The merits of any 
additional changes should be evaluated on their merits if they do 
come up afterwards.

>> 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 
> pixels.
>     int height = 720; /// The default height of the window in 
> pixels.
> }
> ```
>
> 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.

See small examples like that aren't indicative of actual code. 
Struct settings I've used look more like this, that you usually 
can't see in one full screen window when everything is on one 
line:

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
     @("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
     @("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
     @("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
     @("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
     @("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
     @("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
     @("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
     @("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
     @("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
}

struct WindowSettings
{
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
     int width = 1280; /// default window width in pixels
     int height = 720; /// default window height in pixels
}

Even that is still small in comparison. You could put everything 
on one line but then you are going to be going past any 
reasonable width of code. It'd make it even more unreadable if 
the doc is longer than usual as well. It'll just be doubling the 
width instead of the height. Neither is ideal.