www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - cleaning up the spec: function.html vs memory-safe-d.html

The description of D's safety system is currently spread over (at least) 
two pages in the spec:

1) https://dlang.org/spec/function.html
2) https://dlang.org/spec/memory-safe-d.html

Most of the content on memory-safe-d.html can also be found on 
function.html in more "speccy" language.

But for some reason, memory-safe-d.html has descriptions of `scope` and 
`return` parameters that seem to be missing from function.html. Maybe 
the author of those accidentally picked to wrong spot to add them?

To reduce confusion, I suggest to eliminate the duplication.

Two ways to go about it:

A) Move the "Scope and Return Parameters" section to function.html. If 
there's anything else that's not already on function.html, move that 
too. Delete the duplicated content from memory-safe-d.html. It should be 
empty now. "Cool URIs don't change" [1], so leave memory-safe-d.html 
itself up and let it link to <function.html#function-safety>.

B) Extract everything safety-related from function.html and move it to 
memory-safe-d.html. Again, put links from the old spots to the new one.

Option A is probably easier.

I'm throwing this out there, because I'm probably not going to pursue 
this. But I think it would help improve the spec. Maybe someone wants to 
have a got at it?

[1] https://www.w3.org/Provider/Style/URI.html
May 28