Some feedback on the website.

Walter Bright via Digitalmars-d digitalmars-d at puremagic.com
Thu Dec 17 12:08:24 PST 2015


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.


More information about the Digitalmars-d mailing list