Another use case for __traits(docComment)

[Jab]

On Thursday, 14 November 2019 at 07:50:31 UTC, Jonathan Marler 
wrote:
> On Thursday, 14 November 2019 at 03:17:38 UTC, Steven 
> Schveighoffer wrote:
>> On 11/13/19 6:03 PM, Adam D. Ruppe wrote:
>>> On Wednesday, 13 November 2019 at 22:53:49 UTC, Steven 
>>> Schveighoffer wrote:
>>>> I'm trying to save the reviewers and the maintainers. Code 
>>>> review shouldn't include reviewing stuff that isn't compiled.
>>> 
>>> Documentation is a key component of code review. And any code 
>>> reviewer would surely be skeptical of a __trait(getDoc) that 
>>> does anything other than use it for documentation.
>>
>> Where it starts becoming a problem is when users of a library 
>> say "you changed your docs, and it broke my code". This is 
>> always the argument against named parameters (you changed 
>> parameter X's name, and it broke my code).
>>
>
> I'm in the camp of having parameters names "private by default" 
> and requiring libraries to opt-in to exposing them.  By my 
> estimate, named parameters are only useful about 15% of the 
> time.
>  Up till now, D code is written assuming that parameter names 
> are private.  They're inconsistent and not well thought out 
> because they were never part of the function interface. We 
> could come up with naming standards and go through all the code 
> to fix this, which would be a big effort, but it's hard to 
> justify if only a small percentage of functions would actually 
> benefit from named parameters.  By making them "opt-in" you can 
> fix these things before you expose them.

That shouldn't be up to the developer of the library. If I want 
to use named parameters and I go look at the function and I see 
the author gave them horrible names. I'm probably not going to 
continue to use it and I'd probably find a different library to 
use. It's already considered bad practice to give parameters bad 
names. It is unfortunate that Phobos has some horrible names but 
it doesn't really follow a lot of best practices all together.

Making them opt-in makes the feature pointless and more 
convoluted. It's the user's choice whether they want to use them 
or not. It shouldn't be the author of a library dictating where 
the user can use named parameters.

I've seen library maintainers for C++ include function parameter 
name changes as part of the change log. Even though C++ doesn't 
have named parameters. Cause in reality the parameter name is 
already part of the interface and documentation of a function. 
That's some of the only information a user of the library sees 
when they go look at it. Developers should be giving them 
meaningful names, with or without named parameters. I don't think 
we should make a feature more convoluted because some individuals 
have bad naming practices in general.