Improve the API doc description of the SmallArray primitive types

Say how it differs from Array in terms of size and performance.
These are primitives so it's also ok to talk a bit about implementation
details like card tables.

1 files changed, 16 insertions, 2 deletions

diff --git a/compiler/prelude/primops.txt.pp b/compiler/prelude/primops.txt.pp
index dfc1421d81..764ba103f2 100644
--- a/compiler/prelude/primops.txt.pp
+++ b/compiler/prelude/primops.txt.pp
@@ -843,8 +843,22 @@ primop CasArrayOp  "casArray#" GenPrimOp
 section "Small Arrays"
 
 	{Operations on {\tt SmallArray\#}. A {\tt SmallArray\#} works
-         just like an {\tt Array\#}, except that its implementation is
-         optimized for small arrays (i.e. no more than 128 elements.)}
+         just like an {\tt Array\#}, but with different space use and
+         performance characteristics (that are often useful with small
+         arrays). The {\tt SmallArray\#} and {\tt SmallMutableArray#}
+         lack a `card table'. The purpose of a card table is to avoid
+         having to scan every element of the array on each GC by
+         keeping track of which elements have changed since the last GC
+         and only scanning those that have changed. So the consequence
+         of there being no card table is that the representation is
+         somewhat smaller and the writes are somewhat faster (because
+         the card table does not need to be updated). The disadvantage
+         of course is that for a {\tt SmallMutableArray#} the whole
+         array has to be scanned on each GC. Thus it is best suited for
+         use cases where the mutable array is not long lived, e.g.
+         where a mutable array is initialised quickly and then frozen
+         to become an immutable {\tt SmallArray\#}.
+        }
 
 ------------------------------------------------------------------------