deploy: 2680eb5

docs/overview/index.html

@@ -1660,7 +1660,17 @@ <h3 id=procedure-type>Procedure type <a class=text-decoration-none href=#procedu
 </code></pre><p>A <code>bit_field</code> is different from a <code>struct</code> in that you must specify the backing type. This backing type must be an integer or a fixed-length array of integers. This is useful if there needs to be a specific alignment or access pattern for the record.</p>
 <pre><code class=language-odin data-lang=odin>Foo :: bit_field u32 {...}
 Foo :: bit_field [4]u8 {...}
-</code></pre><h4 id=calling-conventions>Calling conventions <a class=text-decoration-none href=#calling-conventions>#</a></h4>
+</code></pre><p>Notes:</p>
+<ul>
+<li>If <em>all</em> of the fields in a <code>bit_field</code> are 1-bit in size and are a boolean, please considering using a <a href=#bit-sets><code>bit_set</code></a> instead.</li>
+<li>Odin&rsquo;s <code>bit_field</code> and C&rsquo;s bit-fields may not be compatible
+<ul>
+<li>Odin&rsquo;s <code>bit_field</code>s have a well defined layout (Least-Significant-Bit)</li>
+<li>C&rsquo;s bit fields on <code>struct</code>s are undefined and are not portable across targets and compilers</li>
+</ul>
+</li>
+</ul>
+<h4 id=calling-conventions>Calling conventions <a class=text-decoration-none href=#calling-conventions>#</a></h4>
 <p>Odin supports the following calling conventions:</p>
 <ul>
 <li><strong>odin</strong> - default convention used for an Odin <strong>proc</strong>. It is the same as <strong>cdecl</strong> but passes an implicit <code>context</code> pointer on each call. (<strong>Note:</strong> This is subject to change)</li>