Season of Docs

[Mike Franklin]

On Friday, 15 March 2019 at 16:52:12 UTC, Seb wrote:

> Where do you think D has the deepest need of good technical 
> documentation?

The `return` and `scope` attribute (e.g. DIP25 and DIP1000) need 
a lot of help.  In addition to the semantics themselves, there 
are other behaviors that need documentation:

1) Attributes are often inferred, but how and when this inference 
occurs is not documented.  I remember playing around to try and 
figure it out, and 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.

2) Walter introduced a convention where the first parameter of a 
function is treated differently than others.  This behavior needs 
to be documented (and should be reverted, IMO). See 
https://github.com/dlang/dmd/pull/8504

It is critical that the developer that introduces a feature 
document it sufficiently.  After the documentation is primed with 
the initial explanation, the rest of the community can inherit it 
and build on it.  But without that initial documentation, noone 
else knows what to write.  See 
https://forum.dlang.org/post/jmdlnsijowsdmiuhfrwn@forum.dlang.org

Mike