Season of Docs

[Mike Franklin]

On Tuesday, 19 March 2019 at 05:10:57 UTC, Walter Bright wrote:
> On 3/18/2019 6:59 PM, Mike Franklin wrote:
>> I found that the even when explicitly marking something with 
>> `scope`, the compiler removed it due to the inference rules.  
>> That was alarming to me.
>
> I don't know of a case where it does that. It would be a bug.

I sent you an e-mail about it on June 28, 2018.  Here's the code 
in the compiler that I alluded to.

https://github.com/dlang/dmd/blob/25b1f0a55159d2addfc2edd5ff1de3c8c983f66e/src/dmd/typesem.d#L1358-L1363

```D
if (fparam.storageClass & STC.scope_ && 
!fparam.type.hasPointers() && fparam.type.ty != Ttuple)
{
     fparam.storageClass &= ~STC.scope_;
     if (!(fparam.storageClass & STC.ref_))
         fparam.storageClass &= ~STC.return_;
}
```

The following code fails as a result:
```D
void foo(scope int p);

static assert(__traits(getParameterStorageClasses, foo, 0)[0] == 
"scope");
```

Revisiting this just now, I realize that if I make the parameter 
`scope int* p` instead of `scope int p` it works fine.  Maybe 
that is by design (yuck!), maybe it's not, I don't know because 
it's not sufficiently documented.

Regardless, the compiler shouldn't be removing anything the user 
explicitly specifies.  Instead, it should give the user an error.

I can't submit bug reports against a non-existent specification.  
Without the spec, how am I supposed to know whether or not its a 
bug, and how is a developer supposed to know what to do for the 
fix?  It's a no-win situation.

Also, some of your DIP 1000 PRs should not have been merged 
because they lacked enough documentation for anyone to do a 
proper review, but my concerns fell on deaf ears.  And just any 
documentation is not sufficient.  To this day, you're still 
fielding questions on the forum because noone knows how it's 
supposed to work; they're just speculating.  Perhaps if you 
documented it, others might know how to leverage it and help you 
with your immediate goal of improving Phobos.

Mike