November 15, 2019
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.
November 15, 2019
On Friday, 15 November 2019 at 17:15:12 UTC, Jab wrote:
> 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:

As you get more and more struct members the chance that the documentation comment can actually double as user-facing comments becomes smaller and smaller.
Trying to keep everything simple and compact like that is not going to scale, as soon as e.g. your application gets localized and supports foreign languages your one-liner multi-purpose documentation comments have to go anyway.


November 19, 2019
On Friday, 15 November 2019 at 17:57:59 UTC, Dennis wrote:
> On Friday, 15 November 2019 at 17:15:12 UTC, Jab wrote:
>> 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:
>
> As you get more and more struct members the chance that the documentation comment can actually double as user-facing comments becomes smaller and smaller.
> Trying to keep everything simple and compact like that is not going to scale, as soon as e.g. your application gets localized and supports foreign languages your one-liner multi-purpose documentation comments have to go anyway.

Docs don't really ever get localized. Otherwise phobos, D, and basically all programming languages all have the same problem.
November 19, 2019
On Tuesday, 19 November 2019 at 05:30:46 UTC, Jab wrote:
> Docs don't really ever get localized.

Yeah but you want to make documentation comment also be the explanation text that appears in the GUI of an application (in this example), which might get localized.
1 2 3 4 5
Next ›   Last »