[spec] Document ref and out parameters

[ntrel]

• Split the ref example from the out examples, and put it first.
• Briefly describe each.
• Tweak the scope description.

[dlang-bot]

Thanks for your pull request and interest in making D better, @ntrel! We are looking forward to reviewing it, and you should be hearing from a maintainer soon.
Please verify that your PR follows this checklist:

• My PR is fully covered with tests (you can see the coverage diff by visiting the details link of the codecov check)
• My PR is as minimal as possible (smaller, focused PRs are easier to review than big ones)
• I have provided a detailed rationale explaining my changes
• New or modified functions have Ddoc comments (with Params: and Returns:)

Please see CONTRIBUTING.md for more information.

---

If you have addressed all reviews or aren't sure how to proceed, don't hesitate to ping us with a simple comment.

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

[JinShil]

Since DIP 25 and DIP 1000 are experimental features (at least I think they are). I'd prefer if we had a separate document in the spec describing their semantics. Then when they are official, their documentation can be folded into the spec.

[ntrel]

-dip25 is already in the docs (I wrote it):
https://dlang.org/spec/function.html#return-ref-parameters

[JinShil]

Thanks. We're lucky to have it. But I think it should be moved until DIP 25 and 1000 are official.

[ntrel]

Probably this just needs someone to do the git commit --amend trick to restart DAutoTest. (I don't have my terminal available ATM).

[ntrel]

--amend retriggered tests, but now there's a different error. AFAICT this is the problem (which I also get for #2454 but with different input line numbers):

! Extra }, or forgotten \endgroup.
<recently read> \egroup 
                        
l.19214 }
         
? 
! Emergency stop.
<recently read> \egroup 
                        
l.19214 }
         
!  ==> Fatal error occurred, no output PDF file produced!

[ntrel]

Same test error for #2459 - it seems anything that touches spec/function.dd gets this error. @wilzbach Any idea?

[ntrel]

I forgot about this, but the test error blocking this has long since gone away - which then revealed an actual error, now fixed.