Another use case for __traits(docComment)

Steven Schveighoffer schveiguy at gmail.com
Thu Nov 14 03:17:38 UTC 2019


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).

Anything that becomes observable at compile-time now becomes part of the 
API.

Theoretically, even a runtime string could cause this. But there is much 
less possibility for abuse, and at least the compiler doesn't write 
*different* binary instructions based on comments.

> (and you could actually even static assert it is written reasonably with 
> the trait but i could see that being hated too lol.)

Isn't that what commit hooks are for? ;)

-Steve


More information about the Digitalmars-d mailing list