From a51929b73d85706b307867005775f72482590602 Mon Sep 17 00:00:00 2001
From: "Papp, Gyozo" <pappgyozo@gmail.com>
Date: Sun, 15 Sep 2024 13:28:04 +0200
Subject: [PATCH] doc,langref: mention diffs of Zig and C packed structs

---
 doc/langref.html.in | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/doc/langref.html.in b/doc/langref.html.in
index 9f12829349fa..b5643b6c4148 100644
--- a/doc/langref.html.in
+++ b/doc/langref.html.in
@@ -2250,6 +2250,40 @@ or
       </p>
       {#header_close#}
 
+      <p>
+      A Zig packed struct behaves differently when it stands alone in the memory (non-packed
+      location) and when it is embedded in another packed struct or union as a field (packed
+      location). A Zig packed struct is also not the same as a packed struct attribute in C.
+      The following table highlights some differences:
+      </p>
+      <div class="table-wrapper">
+      <table>
+        <caption>Differences between Zig and C packed structs</caption>
+        <thead>
+        <tr>
+          <th scope="col">Property</th>
+          <th scope="col">Zig packed struct in non-packed location</th>
+          <th scope="col">Zig packed struct in packed location</th>
+          <th scope="col">C packed struct</th>
+        </tr>
+        </thead>
+        <tbody>
+        <tr>
+            <th scope="row">Size</th>
+            <td>Size of the backing integer.</td>
+            <td>Total number of bits of the fields.</td>
+            <td>Total number of bytes of the fields.</td>
+        </tr>
+        <tr>
+            <th scope="row">Alignment</th>
+            <td>Alignment of the backing integer.</td>
+            <td>Can start at any bit offset.</td>
+            <td>1 byte.</td>
+        </tr>
+        </tbody>
+      </table>
+      </div>
+
       {#header_open|Struct Naming#}
       <p>Since all structs are anonymous, Zig infers the type name based on a few rules.</p>
       <ul>