Another use case for __traits(docComment)

[Jab]

On Thursday, 14 November 2019 at 09:54:35 UTC, Dennis wrote:
> On Thursday, 14 November 2019 at 05:03:49 UTC, Jab wrote:
>> With that kind of justification no new features should ever be 
>> added. Not to mention bug fixes that just cause no bugs. We 
>> should just stop making changes all together.
>
> I just said that every feature has (hidden) cost, not that that 
> cost is never justified.

Your making it sound like it isn't justified because of those 
hidden costs.

>> They probably want to, because the old way is impeding the new 
>> method, you can't use CTFE to construct a string.
>
> That's not the point, the point is that it always starts with 
> "but I just want X, nothing more!", and later inevitably 
> someone wants Y too. Concretely in that case: "It can live 
> peacefully beside your preferred design with the scopes." 
> followed by the PR to deprecate extern(C++, identifier).

The whole purpose of extern(C++, "") was because extern(C++, 
identifier) was inadequate.

If you want to look at it one way. The extern(C++, "") syntax was 
only wanted because the extern(C++, identifier) was there. Should 
we have not added extern(C++, identifier) to D to begin with? 
People are going to want to make changes to things they don't 
like. Before extern(C++, identifer) was added people were 
probably asking for a way to link with C++ mangling. 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?

>> Here's a counter example to your example: 
>> https://github.com/dlang/dmd/pull/10013
>
> I actually think that got merged too quickly without thinking 
> all special cases and consequences through.

Has there been any consequences?

>> I wouldn't really say it's a new "feature". It'd just be 
>> exposing the information that is already available
>
> Whatever you call it, it's another source of complexity as I 
> mentioned before.
>
>> How would you duplicate this doc:
>>
>> /// ditto
>
> Put the UDA string in an enum?
> ```
> enum string fooComment = "does foo"
> /// does foo
> @(fooComment) void foo(int a);
> /// ditto
> @(fooComment) void foo(string a);
> ```
>
> It's hard to argue what the best current solution is without a 
> concrete usecase.
> If you write some functions / fields yourself, you can write 
> some UDA strings that may be redundant with your doc comments.
> If you want to expose documentation from an existing library 
> (e.g. Phobos), it can be extracted beforehand instead.

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


enum cmpComment = `
Performs a lexicographical comparison on two
$(REF_ALTTEXT input ranges, isInputRange, std,range,primitives).
Iterating `r1` and `r2` in lockstep, `cmp` compares each element
`e1` of `r1` with the corresponding element `e2` in `r2`. If one
of the ranges has been finished, `cmp` returns a negative value
if `r1` has fewer elements than `r2`, a positive value if `r1`
has more elements than `r2`, and `0` if the ranges have the same
number of elements.
If the ranges are strings, `cmp` performs UTF decoding
appropriately and compares the ranges one code point at a time.
A custom predicate may be specified, in which case `cmp` performs
a three-way lexicographical comparison using `pred`. Otherwise
the elements are compared using `opCmp`.
Params:
     pred = Predicate used for comparison. Without a predicate
         specified the ordering implied by `opCmp` is used.
     r1 = The first range.
     r2 = The second range.
Returns:
     `0` if the ranges compare equal. A negative value if `r1` is 
a prefix of `r2` or
     the first differing element of `r1` is less than the 
corresponding element of `r2`
     according to `pred`. A positive value if `r2` is a prefix of 
`r1` or the first
     differing element of `r2` is less than the corresponding 
element of `r1`
     according to `pred`.
Note:
     An earlier version of the documentation incorrectly stated 
that `-1` is the
     only negative value returned and `1` is the only positive 
value returned.
     Whether that is true depends on the types being compared.`;

/**********************************
Performs a lexicographical comparison on two
$(REF_ALTTEXT input ranges, isInputRange, std,range,primitives).
Iterating `r1` and `r2` in lockstep, `cmp` compares each element
`e1` of `r1` with the corresponding element `e2` in `r2`. If one
of the ranges has been finished, `cmp` returns a negative value
if `r1` has fewer elements than `r2`, a positive value if `r1`
has more elements than `r2`, and `0` if the ranges have the same
number of elements.
If the ranges are strings, `cmp` performs UTF decoding
appropriately and compares the ranges one code point at a time.
A custom predicate may be specified, in which case `cmp` performs
a three-way lexicographical comparison using `pred`. Otherwise
the elements are compared using `opCmp`.
Params:
     pred = Predicate used for comparison. Without a predicate
         specified the ordering implied by `opCmp` is used.
     r1 = The first range.
     r2 = The second range.
Returns:
     `0` if the ranges compare equal. A negative value if `r1` is 
a prefix of `r2` or
     the first differing element of `r1` is less than the 
corresponding element of `r2`
     according to `pred`. A positive value if `r2` is a prefix of 
`r1` or the first
     differing element of `r2` is less than the corresponding 
element of `r1`
     according to `pred`.
Note:
     An earlier version of the documentation incorrectly stated 
that `-1` is the
     only negative value returned and `1` is the only positive 
value returned.
     Whether that is true depends on the types being compared.
*/
@docComment(cmpComment) auto cmp(R1, R2)(R1 r1, R2 r2);