SE-0377: Document the borrowing and consuming parameter modifiers
#173
Conversation
This documents the `borrowing` and `consuming` parameter modifiers introduced by SE-0377. These are comparatively niche, so I'm only documenting them in the "Reference Manual" section for now. I've structured this by: * Creating a new "Parameter Modifiers" section with a brief description of the modifiers concept, * Moving the old "In-Out Parameters" description under it, and * Adding a new subsection on Borrowing and Consuming Parameters. I've also adjusted the "In-Out Parameters" introduction so it starts with a code example showing the `inout` syntax and usage. SE-0377: https://github.com/apple/swift-evolution/blob/main/proposals/0377-parameter-ownership-modifiers.md
There was a problem hiding this comment.
Thanks, Tim!
Structurally, I think this is the right place to add this information, and I think the demotion of the in-out section to make a sibling of the borrowing/consuming section is the right approach.
Some of the content about borrowing and consuming is written more like part of the guide than reference, but I can help you clean that up later. If this is feeling too long for the reference, we can start a section in Memory Safety about ownership.
We probably don't need to add examples of exclusivity violations in the reference, because there's already a section that discusses these situations in more detail in "Memory Safety", which is linked at the end of the section.
The formal grammar needs to move at the end of sections, and needs to start with a "Grammar of" line. (When we get grammar we're happy with, we have to update the summary of the grammar manually too.) The new parameter-modifier needs to be added to one of the other productions -- currently, nothing in the grammar refers to this production, so there's no way to "get here" so to speak. I think it could be added to the definition of parameter, although I also see inout is already part of type-annotation, so that might be the place to add borrowing and consuming.
A minor point: How did you decide where to break lines? It looks like you might be hard wrapping at ~60 characters? The existing content breaks lines at clause boundaries, with the idea that each line is a "chunk" of prose that stands on its own to some extent. Most of the existing notes in the TSPL style guide about this tell you why to use semantic line breaks, but maybe more detail there is needed about exactly where to break lines.
Umm.... Is that right? In particular, I don't think we currently allow |
I was a little confused about that, because the earlier sections in this particular file do not provide grammar productions for function declarations, just template examples. |
I believe I've done that. If you see any place I've missed, please let me know (I'm certainly familiar with the old nroff/manpage conventions and do try to follow them strictly. But yes, I do tend to prefer short lines.) |
Looking back through the commit history, that part of the grammar is from commit ba96767, and came from the grammar in SE-0031. Prior to that commit,
Maybe it's hard to follow while editing, but the formal grammar appears at the end of each section. So subsections don't contain their own grammar. For example, the Variable Declaration section has several subsections, and then one "Grammar of a variable declaration" box at the end. Each section ends with a grammar-of box — in the case of Function Declaration, there are nine subsections, so you have to scroll a fair bit. The new grammar productions in all nine of those subsections are collected in the "Grammar of a function declaration" box at the end of the section. Elsewhere in the reference, some subsections have their own grammar-of boxes. For function declarations, I think they're all in one box mostly because the subsections don't introduce much grammar — most of the grammar is the same for regular functions as it is for functions that are throwing, async, nonreturning, and so on. But maybe the Functions section is getting too long, and we should divide up its grammar to make it easier to navigate.
You're exactly correct; the convention here is essentially the same as nroff and man pages. Different writers have different styles for where to break lines and how long a line should be, which is fine. (I can often guess who wrote something in TSPL, based on formatting preferences.) To help keep the content readable in a monospace font, let's prefer I'll take a light revision pass for style and, and then push to this branch. |
- Introduce in prose 'copy' before showing it in code. - Various style changes per Apple and DevPubs style: not using "since" to mean "because", placing "only" directly before the word it modifies, avoiding bare "this", preferring present rather than future tense, and naming of the & operator. - Match typical TSPL style for wording at the start of a reference section and "prints" comments. - Added XXX markers for issues that should block merging this branch.
|
@tbkka Please take a look at my revised version. Most of the changes are Apple or DevPubs style, with some my personal wording preference, and a couple minor changes to order — introducing things before showing them. I left XXX markers for things I want to resolve before merging this branch because the build script for TSPL treats them as a hard error, ensuring none get left behind. I see you have some TODO markers near the end. Were those things you'd like to include in this PR, or possibilities for the future? I'm also planning to re-read the SE proposal again while looking at the reference, checking for additional information we should include. |
|
(Ping for @tbkka) |
The grammar used to allow `inout` on any type annotation, following the grammar changes described in SE-0031. However, that isn't correct -- parameter modifiers like `inout` are allowed only in a function type or a function declaration, as part of a parameter's type. Separating the productions for type-annotation and parameter-type-annotation adds a small amount of duplication to the grammar, but it removes the overproduction.
|
Your changes look good! |
Co-authored-by: Tim Kientzle <tkientzle@apple.com>
We do actually use "lifetime" already, so no issue with that here. Avoiding "retain" which could be confused for manual reference counting, and "alive" which requires extending the "object lifetime" metaphor.
There was a problem hiding this comment.
Before I merge, I want to have someone double check the grammar changes with me. Otherwise I think this is ready now.
The new to-do markers that this PR adds are both things we can add later:
-
borrowingandconsumingkeywords with noncopyable argument types. We don't discuss noncopyable types yet in TSPL (rdar://110848216). -
Any change of parameter modifier is ABI-breaking. TSPL doesn't discuss ABI stability other than
@frozen.
Per TR from Tim Kientzle, this shouldn't be documented here. TSPL doesn't really have any place where we document the function-calling conventions (that's really more ABI than language). The fact that we currently always copy, even though it might get optimized out, is an implementation detail.
Co-authored-by: Tim Kientzle <tkientzle@apple.com>
Co-authored-by: Rex <rex.fenley@gmail.com>
Edits from rdar://116694613 Co-authored-by: Chuck Toporek <chuck_toporek@apple.com>
Co-authored-by: Chuck Toporek <76215+chuckdude@users.noreply.github.com>
This got missed in PR swiftlang#173 when adding them.
This documents the
borrowingandconsumingparameter modifiers introduced by SE-0377.These are comparatively niche, so I'm only documenting them in the "Reference Manual" section for now.
I've structured this by:
I've also adjusted the "In-Out Parameters" introduction so it starts with a code example showing the
inoutsyntax and usage.Fixes: rdar://116031853