On 12/17/2015 4:27 AM, John Colvin wrote:
The number of macros bothers me, but mostly it's the complete lack of
documentation and guidelines on where/how to use them*.
It's pretty unreasonable to expect someone submitting a passing doc fix to
1) find where the macros are defined
2) decipher them
3) use the "right" one**
It's just too much unpleasant work for people to bother with.
*If there is documentation and guidelines on this and I don't know about it,
consider what it would be like for someone who doesn't spend many hours a week
on the various subdomains of dlang.org: it might as well not exist!
**there must be some reasons for the existence of all of those macros, so
presumably there are good and bad choices for certain situations, even if
nothing is obviously broken using the bad choice. Sure, we might say "submit
something naïve and then people will help you fix it", but that's still a
barrier to entry; 1) how were they supposed to know we felt that way about
submissions? 2) people don't like looking stupid.
Documentation in the std.ddoc files would certainly help. $(COMMENT this is
comment) is a convention that works well. PRs to add explanatory comments are
welcome.
