Skip to content

Commit 9a8f5a7

Browse files
glessardglessard
committed
[span] update more doc-comments
1 parent 6272ad6 commit 9a8f5a7

File tree

1 file changed

+38
-34
lines changed

1 file changed

+38
-34
lines changed

‎stdlib/public/core/Span/RawSpan.swift

Lines changed: 38 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -82,13 +82,12 @@ extension RawSpan {
8282

8383
/// Unsafely create a `RawSpan` over initialized memory.
8484
///
85-
/// The memory in `buffer` must be owned by the instance `owner`,
86-
/// meaning that as long as `owner` is alive the memory will remain valid.
85+
/// The memory in `buffer` must remain valid, initialized and immutable
86+
/// throughout the lifetime of the newly-created `RawSpan`.
87+
/// Failure to maintain this invariant results in undefined behaviour.
8788
///
8889
/// - Parameters:
8990
/// - buffer: an `UnsafeRawBufferPointer` to initialized memory.
90-
/// - owner: a binding whose lifetime must exceed that of
91-
/// the newly created `RawSpan`.
9291
@_disallowFeatureSuppression(NonescapableTypes)
9392
@_alwaysEmitIntoClient
9493
//FIXME: should be @lifetime(borrow <argname>) rdar://138672380
@@ -101,6 +100,14 @@ extension RawSpan {
101100
)
102101
}
103102

103+
/// Unsafely create a `RawSpan` over initialized memory.
104+
///
105+
/// The memory in `buffer` must remain valid, initialized and immutable
106+
/// throughout the lifetime of the newly-created `RawSpan`.
107+
/// Failure to maintain this invariant results in undefined behaviour.
108+
///
109+
/// - Parameters:
110+
/// - buffer: an `UnsafeRawBufferPointer` to initialized memory.
104111
@_disallowFeatureSuppression(NonescapableTypes)
105112
@_alwaysEmitIntoClient
106113
//FIXME: should be @lifetime(borrow <argname>) rdar://138672380
@@ -113,13 +120,12 @@ extension RawSpan {
113120

114121
/// Unsafely create a `RawSpan` over initialized memory.
115122
///
116-
/// The memory in `buffer` must be owned by the instance `owner`,
117-
/// meaning that as long as `owner` is alive the memory will remain valid.
123+
/// The memory in `buffer` must remain valid, initialized and immutable
124+
/// throughout the lifetime of the newly-created `RawSpan`.
125+
/// Failure to maintain this invariant results in undefined behaviour.
118126
///
119127
/// - Parameters:
120-
/// - buffer: an `UnsafeMutableRawBufferPointer` to initialized memory.
121-
/// - owner: a binding whose lifetime must exceed that of
122-
/// the newly created `RawSpan`.
128+
/// - buffer: an `UnsafeRawBufferPointer` to initialized memory.
123129
@_disallowFeatureSuppression(NonescapableTypes)
124130
@_alwaysEmitIntoClient
125131
//FIXME: should be @lifetime(borrow <argname>) rdar://138672380
@@ -142,15 +148,14 @@ extension RawSpan {
142148

143149
/// Unsafely create a `RawSpan` over initialized memory.
144150
///
145-
/// The memory over `count` bytes starting at
146-
/// `pointer` must be owned by the instance `owner`,
147-
/// meaning that as long as `owner` is alive the memory will remain valid.
151+
/// The region of memory representing `byteCount` bytes starting at `pointer`
152+
/// must remain valid, initialized and immutable
153+
/// throughout the lifetime of the newly-created `RawSpan`.
154+
/// Failure to maintain this invariant results in undefined behaviour.
148155
///
149156
/// - Parameters:
150157
/// - pointer: a pointer to the first initialized byte.
151158
/// - byteCount: the number of initialized bytes in the span.
152-
/// - owner: a binding whose lifetime must exceed that of
153-
/// the newly created `RawSpan`.
154159
@_disallowFeatureSuppression(NonescapableTypes)
155160
@_alwaysEmitIntoClient
156161
//FIXME: should be @lifetime(borrow <argname>) rdar://138672380
@@ -165,13 +170,12 @@ extension RawSpan {
165170

166171
/// Unsafely create a `RawSpan` over initialized memory.
167172
///
168-
/// The memory in `buffer` must be owned by the instance `owner`,
169-
/// meaning that as long as `owner` is alive the memory will remain valid.
173+
/// The memory in `buffer` must remain valid, initialized and immutable
174+
/// throughout the lifetime of the newly-created `RawSpan`.
175+
/// Failure to maintain this invariant results in undefined behaviour.
170176
///
171177
/// - Parameters:
172178
/// - buffer: an `UnsafeRawBufferPointer` to initialized memory.
173-
/// - owner: a binding whose lifetime must exceed that of
174-
/// the newly created `RawSpan`.
175179
@_disallowFeatureSuppression(NonescapableTypes)
176180
@_alwaysEmitIntoClient
177181
//FIXME: should be @lifetime(borrow <argname>) rdar://138672380
@@ -184,11 +188,12 @@ extension RawSpan {
184188

185189
/// Unsafely create a `RawSpan` over initialized memory.
186190
///
187-
/// The memory in `buffer` must be valid and initialized
188-
/// for at least as long as the returned `RawSpan` exists.
191+
/// The memory in `buffer` must remain valid, initialized and immutable
192+
/// throughout the lifetime of the newly-created `RawSpan`.
193+
/// Failure to maintain this invariant results in undefined behaviour.
189194
///
190195
/// - Parameters:
191-
/// - buffer: a raw buffer to initialized memory.
196+
/// - buffer: an `UnsafeRawBufferPointer` to initialized memory.
192197
@_disallowFeatureSuppression(NonescapableTypes)
193198
@_alwaysEmitIntoClient
194199
//FIXME: should be @lifetime(borrow <argname>) rdar://138672380
@@ -203,13 +208,12 @@ extension RawSpan {
203208

204209
/// Unsafely create a `RawSpan` over initialized memory.
205210
///
206-
/// The memory in `buffer` must be owned by the instance `owner`,
207-
/// meaning that as long as `owner` is alive the memory will remain valid.
211+
/// The memory in `buffer` must remain valid, initialized and immutable
212+
/// throughout the lifetime of the newly-created `RawSpan`.
213+
/// Failure to maintain this invariant results in undefined behaviour.
208214
///
209215
/// - Parameters:
210-
/// - buffer: an `UnsafeMutableRawBufferPointer` to initialized memory.
211-
/// - owner: a binding whose lifetime must exceed that of
212-
/// the newly created `RawSpan`.
216+
/// - buffer: an `UnsafeRawBufferPointer` to initialized memory.
213217
@_disallowFeatureSuppression(NonescapableTypes)
214218
@_alwaysEmitIntoClient
215219
//FIXME: should be @lifetime(borrow <argname>) rdar://138672380
@@ -222,11 +226,12 @@ extension RawSpan {
222226

223227
/// Unsafely create a `RawSpan` over initialized memory.
224228
///
225-
/// The memory in `buffer` must be valid and initialized
226-
/// for at least as long as the returned `RawSpan` exists.
229+
/// The memory in `buffer` must remain valid, initialized and immutable
230+
/// throughout the lifetime of the newly-created `RawSpan`.
231+
/// Failure to maintain this invariant results in undefined behaviour.
227232
///
228233
/// - Parameters:
229-
/// - buffer: a raw buffer to initialized memory.
234+
/// - buffer: an `UnsafeRawBufferPointer` to initialized memory.
230235
@_disallowFeatureSuppression(NonescapableTypes)
231236
@_alwaysEmitIntoClient
232237
//FIXME: should be @lifetime(borrow <argname>) rdar://138672380
@@ -241,15 +246,14 @@ extension RawSpan {
241246

242247
/// Unsafely create a `RawSpan` over initialized memory.
243248
///
244-
/// The memory over `count` bytes starting at
245-
/// `pointer` must be owned by the instance `owner`,
246-
/// meaning that as long as `owner` is alive the memory will remain valid.
249+
/// The region of memory representing `byteCount` bytes starting at `pointer`
250+
/// must remain valid, initialized and immutable
251+
/// throughout the lifetime of the newly-created `RawSpan`.
252+
/// Failure to maintain this invariant results in undefined behaviour.
247253
///
248254
/// - Parameters:
249255
/// - pointer: a pointer to the first initialized byte.
250256
/// - byteCount: the number of initialized bytes in the span.
251-
/// - owner: a binding whose lifetime must exceed that of
252-
/// the newly created `RawSpan`.
253257
@_disallowFeatureSuppression(NonescapableTypes)
254258
@_alwaysEmitIntoClient
255259
//FIXME: should be @lifetime(borrow <argname>) rdar://138672380

0 commit comments

Comments
 (0)