diff --git a/LUA_API.rst b/LUA_API.rst
index 9fb37375d..0736b02b7 100644
--- a/LUA_API.rst
+++ b/LUA_API.rst
@@ -219,12 +219,21 @@ Bitfield references
-------------------
Bitfields behave like special fixed-size containers.
-The ``_enum`` property points to the bitfield type.
+Consider them to be something in between structs and
+fixed-size vectors.
+The ``_enum`` property points to the bitfield type.
Numerical indices correspond to the shift value,
and if a subfield occupies multiple bits, the
``ipairs`` order would have a gap.
+Since currently there is no API to allocate a bitfield
+object fully in GC-managed lua heap, consider using the
+lua table assignment feature outlined below in order to
+pass bitfield values to dfhack API functions that need
+them, e.g. ``matinfo:matches{metal=true}``.
+
+
Named types
===========
diff --git a/Lua API.html b/Lua API.html
index 1576652d6..568090a76 100644
--- a/Lua API.html
+++ b/Lua API.html
@@ -534,10 +534,17 @@ use #ref, or just
Bitfields behave like special fixed-size containers.
-The _enum property points to the bitfield type.
-Numerical indices correspond to the shift value,
+Consider them to be something in between structs and
+fixed-size vectors.
+The _enum property points to the bitfield type.
+Numerical indices correspond to the shift value,
and if a subfield occupies multiple bits, the
ipairs order would have a gap.
+Since currently there is no API to allocate a bitfield
+object fully in GC-managed lua heap, consider using the
+lua table assignment feature outlined below in order to
+pass bitfield values to dfhack API functions that need
+them, e.g. matinfo:matches{metal=true}.