diff --git a/src/README.md b/src/README.md
index 283f64a27f..ea61b8466d 100644
--- a/src/README.md
+++ b/src/README.md
@@ -355,8 +355,8 @@ packets are allocated and freed.
 
 ```
 struct packet {
-    uint8_t  data[packet.max_payload];
     uint16_t length;
+    uint8_t  data[packet.max_payload];
 };
 ```
 
@@ -393,18 +393,21 @@ error is raised if there is not enough space in *packet* to accomodate
 — Function **packet.prepend** *packet*, *pointer*, *length*
 
 Prepends *length* bytes starting at *pointer* to the front of
-*packet*. An error is raised if there is not enough space in *packet* to
+*packet*, taking ownership of the packet and returning a new packet.
+An error is raised if there is not enough space in *packet* to
 accomodate *length* additional bytes.
 
 — Function **packet.shiftleft** *packet*, *length*
 
-Truncates *packet* by *length* bytes from the front. *Length* must be less than
-or equal to `length` of *packet*.
+Take ownership of *packet*, truncate it by *length* bytes from the
+front, and return a new packet. *Length* must be less than or equal to
+`length` of *packet*.
 
 — Function **packet.shiftright** *packet*, *length*
 
-Moves *packet* payload to the right by *length* bytes, growing *packet* by
-*length*. The sum of *length* and `length` of *packet* must be less than or
+Take ownership of *packet*, moves *packet* payload to the right by
+*length* bytes, growing *packet* by *length*. Returns a new packet.
+The sum of *length* and `length` of *packet* must be less than or
 equal to `packet.max_payload`.
 
 — Function **packet.from_pointer** *pointer*, *length*