Another use case for __traits(docComment)

[Jonathan Marler]

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 being said, Ddoc comments differ from named parameters. DDoc 
comments are already exposed to the compiler and external tools.  
Unlike parameter names, they are already written to be publicly 
consumed by external components.  Adding another access point via 
__traits is less significant since this information is already 
exposed to other external components. DDoc comments are also 
"opt-in".  You can use regular comments if you don't want to 
expose/maintain well-formatted metadata about your code.

I'd also be careful about thinking about DDoc comments like they 
are "comments". DDoc comments may be called comments but they 
don't fit the criteria of normal comments.  They have their own 
format (a mini language within D) and have lexical significance 
to the compiler. They actually behave more like user-defined 
attributes rather than normal comments.  I have a feeling that if 
they were called something else like "DDoc Metadata" rather than 
comments then there wouldn't be much resistance to exposing them 
via __traits.