diff --git a/docs/AAllocator-reference.rst b/docs/AAllocator-reference.rst
index 4bb0150..7ae4ea8 100644
--- a/docs/AAllocator-reference.rst
+++ b/docs/AAllocator-reference.rst
@@ -56,6 +56,11 @@ Class
 
 .. doxygenclass:: xo::mm::AAllocator
 
+Types
+-----
+
+.. doxygengroup:: mm-allocator-type-traits
+
 Methods
 -------
 
diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt
index 55ceed6..aefd71f 100644
--- a/docs/CMakeLists.txt
+++ b/docs/CMakeLists.txt
@@ -6,6 +6,7 @@ xo_docdir_sphinx_config(
     index.rst
     glossary.rst
     implementation.rst
+    AAllocator-reference.rst
     ArenaConfig-reference.rst
     DArena-reference.rst
     #install.rst
diff --git a/docs/examples.rst b/docs/examples.rst
new file mode 100644
index 0000000..a60bebd
--- /dev/null
+++ b/docs/examples.rst
@@ -0,0 +1,40 @@
+.. _examples:
+
+.. toctree
+    :maxdepth: 2
+
+Examples
+========
+
+Arena allocation
+-----------------
+
+.. code-block:: cpp
+
+    #include <xo/alloc2/arena/DArena.hpp>
+
+    using namespace xo::mm;
+    using namespace std;
+
+
+Create an arena:
+
+.. code-block:: cpp
+
+    // create arena, size 64k
+    DArena arena = DArena::map(ArenaConfig { .size_ = 64*1024; });
+
+    cout << arena.lo() << ".." << arena.hi();
+
+This determines a VM memory address range.
+Actually address range is rounded up to a whole number of VM pages.
+Size here is a hard maximum. It cannot be changed for this arena instance.
+
+.. code-block:: cpp
+
+    arena.reserved(); // 64k
+    arena.committed(); // 0k
+    arena.available(); // 0k
+
+Although we know the address range for arena, it doesn't own any physical
+memory yet.
diff --git a/docs/index.rst b/docs/index.rst
index 5c666a3..ac8a802 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -3,13 +3,17 @@
 xo-alloc2 documentation
 =======================
 
-xo-alloc2 is intended to provide fast vm-aware arena allocation.
-Next-generation version of xo-alloc.
+xo-alloc2 provides:
 
-Features:
+* Fast vm-aware arena allocation.
+* Allocates uncommitted virtual memory, and commits on demand.
+* When available, uses THP (Transparent Huge Pages) to mitigate pagetable pressure.
+* Optional GC support, with per-alloc header.
 
-* allocates uncommitted virtual memory, and commits on demand.
-* uses THP (Transparent Huge Pages) when available.
+Diagnostic features:
+
+* with alloc headers: forward iterators over individual allocations
+* configurable guard memory between allocations.
 
 Implemented using FOMO (faceted rust-like object model) from xo-facet
 
@@ -17,6 +21,7 @@ Implemented using FOMO (faceted rust-like object model) from xo-facet
     :maxdepth: 2
     :caption: xo-alloc2 contents
 
+    examples
     implementation
     AAllocator-reference
     ArenaConfig-reference
diff --git a/utest/arena.test.cpp b/utest/arena.test.cpp
index 6826dd3..823e205 100644
--- a/utest/arena.test.cpp
+++ b/utest/arena.test.cpp
@@ -4,7 +4,6 @@
  **/
 
 #include "xo/alloc2/Allocator.hpp"
-//#include "xo/alloc2/IAllocator_Any.hpp"
 #include "xo/alloc2/alloc/IAllocator_Xfer.hpp"
 //#include "xo/alloc2/DArena.hpp"
 #include "xo/alloc2/arena/IAllocator_DArena.hpp"