Another use case for __traits(docComment)
johnnymarler at gmail.com
Thu Nov 14 07:50:31 UTC 2019
On Thursday, 14 November 2019 at 03:17:38 UTC, Steven
> 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
More information about the Digitalmars-d