diff --git a/cranelift/docs/ir.rst b/cranelift/docs/ir.rst
index 775362ad69..d0cfa5ff16 100644
--- a/cranelift/docs/ir.rst
+++ b/cranelift/docs/ir.rst
@@ -96,12 +96,16 @@ different types.
 Boolean types
 -------------
 
-Boolean values are either true or false. While this only requires a single bit
-to represent, more bits are often used when holding a boolean value in a
-register or in memory. The :type:`b1` type represents an abstract boolean
-value. It can only exist as an SSA value, it can't be stored in memory or
-converted to another type. The larger boolean types can be stored in memory.
-They are represented as either all zero bits or all one bits.
+Boolean values are either true or false.
+
+The :type:`b1` type represents an abstract boolean value. It can only exist as
+an SSA value, and can't be directly stored in memory. It can, however, be
+converted into an integer with value 0 or 1 by the :inst:`bint` instruction (and
+converted back with :inst:`icmp_imm` with 0).
+
+Several larger boolean types are also defined, primarily to be used as SIMD
+element types. They can be stored in memory, and are represented as either all
+zero bits or all one bits.
 
 .. autocliftype:: b1
 .. autocliftype:: b8
diff --git a/lib/codegen/meta-python/base/types.py b/lib/codegen/meta-python/base/types.py
index bcef9c1d51..9141f4fbce 100644
--- a/lib/codegen/meta-python/base/types.py
+++ b/lib/codegen/meta-python/base/types.py
@@ -4,13 +4,16 @@ The base.types module predefines all the Cranelift scalar types.
 from __future__ import absolute_import
 from cdsl.types import IntType, FloatType, BoolType, FlagsType
 
-#: Boolean.
-b1 = BoolType(1)    #: 1-bit bool. Type is abstract (can't be stored in mem)
+#: Abstract boolean (can't be stored in memory, use bint to convert to 0 or 1).
+b1 = BoolType(1)    #: 1-bit bool.
+
+#: Booleans used as SIMD elements (can be stored in memory, true is all-ones).
 b8 = BoolType(8)    #: 8-bit bool.
 b16 = BoolType(16)  #: 16-bit bool.
 b32 = BoolType(32)  #: 32-bit bool.
 b64 = BoolType(64)  #: 64-bit bool.
 
+# Integers.
 i8 = IntType(8)     #: 8-bit int.
 i16 = IntType(16)   #: 16-bit int.
 i32 = IntType(32)   #: 32-bit int.