[skip ci] Improve the documentation of the CNF primops. In this context, the term "size" is ambiguous and is now avoided. Additionally, the distinction between a CNF and the blocks that comprise it has been emphasize. The vocabulary has been made more consistent with the vocabulary in the C source for CNF.

1 files changed, 40 insertions, 23 deletions

diff --git a/compiler/prelude/primops.txt.pp b/compiler/prelude/primops.txt.pp
index 0053c61152..39e7c4799c 100644
--- a/compiler/prelude/primops.txt.pp
+++ b/compiler/prelude/primops.txt.pp
@@ -2977,15 +2977,29 @@ primop  StableNameToIntOp "stableNameToInt#" GenPrimOp
 
 ------------------------------------------------------------------------
 section "Compact normal form"
+
+        {Primitives for working with compact regions. The {\tt ghc\-compact}
+         library and the {\tt compact} library demonstrate how to use these
+         primitives. The documentation below draws a distinction between
+         a CNF and a compact block. A CNF contains one or more compact
+         blocks. The source file {\tt rts\/sm\/CNF.c}
+         diagrams this relationship. When discussing a compact
+         block, an additional distinction is drawn between capacity and
+         utilized bytes. The capacity is the maximum number of bytes that
+         the compact block can hold. The utilized bytes is the number of
+         bytes that are actually used by the compact block.
+        }
+
 ------------------------------------------------------------------------
 
 primtype Compact#
 
 primop  CompactNewOp "compactNew#" GenPrimOp
    Word# -> State# RealWorld -> (# State# RealWorld, Compact# #)
-   { Create a new Compact with the given size (in bytes, not words).
-     The size is rounded up to a multiple of the allocator block size,
-     and capped to one mega block. }
+   { Create a new CNF with a single compact block. The argument is
+     the capacity of the compact block (in bytes, not words).
+     The capacity is rounded up to a multiple of the allocator block size
+     and is capped to one mega block. }
    with
    has_side_effects = True
    out_of_line      = True
@@ -2993,44 +3007,46 @@ primop  CompactNewOp "compactNew#" GenPrimOp
 primop  CompactResizeOp "compactResize#" GenPrimOp
    Compact# -> Word# -> State# RealWorld ->
    State# RealWorld
-   { Set the new allocation size of the compact. This value (in bytes)
-     determines the size of each block in the compact chain. }
+   { Set the new allocation size of the CNF. This value (in bytes)
+     determines the capacity of each compact block in the CNF. It
+     does not retroactively affect existing compact blocks in the CNF. }
    with
    has_side_effects = True
    out_of_line      = True
 
 primop  CompactContainsOp "compactContains#" GenPrimOp
    Compact# -> a -> State# RealWorld -> (# State# RealWorld, Int# #)
-   { Returns 1\# if the object is contained in the compact, 0\# otherwise. }
+   { Returns 1\# if the object is contained in the CNF, 0\# otherwise. }
    with
    out_of_line      = True
 
 primop  CompactContainsAnyOp "compactContainsAny#" GenPrimOp
    a -> State# RealWorld -> (# State# RealWorld, Int# #)
-   { Returns 1\# if the object is in any compact at all, 0\# otherwise. }
+   { Returns 1\# if the object is in any CNF at all, 0\# otherwise. }
    with
    out_of_line      = True
 
 primop  CompactGetFirstBlockOp "compactGetFirstBlock#" GenPrimOp
    Compact# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
-   { Returns the address and the size (in bytes) of the first block of
-     a compact. }
+   { Returns the address and the utilized size (in bytes) of the
+     first compact block of a CNF.}
    with
    out_of_line      = True
 
 primop  CompactGetNextBlockOp "compactGetNextBlock#" GenPrimOp
    Compact# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr#, Word# #)
-   { Given a compact and the address of one its blocks, returns the
-     next block and its size, or #nullAddr if the argument was the
-     last block in the compact. }
+   { Given a CNF and the address of one its compact blocks, returns the
+     next compact block and its utilized size, or {\tt nullAddr\#} if the
+     argument was the last compact block in the CNF. }
    with
    out_of_line      = True
 
 primop  CompactAllocateBlockOp "compactAllocateBlock#" GenPrimOp
    Word# -> Addr# -> State# RealWorld -> (# State# RealWorld, Addr# #)
-   { Attempt to allocate a compact block with the given size (in
-     bytes, given by the first argument). The {\texttt Addr\#} is a pointer to
-     previous block of the compact or {\texttt nullAddr\#} to create a new compact.
+   { Attempt to allocate a compact block with the capacity (in
+     bytes) given by the first argument. The {\texttt Addr\#} is a pointer
+     to previous compact block of the CNF or {\texttt nullAddr\#} to create a
+     new CNF with a single compact block.
 
      The resulting block is not known to the GC until
      {\texttt compactFixupPointers\#} is called on it, and care must be taken
@@ -3042,13 +3058,13 @@ primop  CompactAllocateBlockOp "compactAllocateBlock#" GenPrimOp
 
 primop  CompactFixupPointersOp "compactFixupPointers#" GenPrimOp
    Addr# -> Addr# -> State# RealWorld -> (# State# RealWorld, Compact#, Addr# #)
-   { Given the pointer to the first block of a compact, and the
+   { Given the pointer to the first block of a CNF and the
      address of the root object in the old address space, fix up
-     the internal pointers inside the compact to account for
+     the internal pointers inside the CNF to account for
      a different position in memory than when it was serialized.
      This method must be called exactly once after importing
-     a serialized compact, and returns the new compact and
-     the new adjusted root address. }
+     a serialized CNF. It returns the new CNF and the new adjusted
+     root address. }
    with
    has_side_effects = True
    out_of_line      = True
@@ -3056,10 +3072,10 @@ primop  CompactFixupPointersOp "compactFixupPointers#" GenPrimOp
 primop CompactAdd "compactAdd#" GenPrimOp
    Compact# -> a -> State# RealWorld -> (# State# RealWorld, a #)
    { Recursively add a closure and its transitive closure to a
-     {\texttt Compact\#}, evaluating any unevaluated components at the
-     same time.  Note: {\texttt compactAdd\#} is not thread-safe, so
+     {\texttt Compact\#} (a CNF), evaluating any unevaluated components
+     at the same time. Note: {\texttt compactAdd\#} is not thread-safe, so
      only one thread may call {\texttt compactAdd\#} with a particular
-     {\texttt Compact#} at any given time.  The primop does not
+     {\texttt Compact\#} at any given time. The primop does not
      enforce any mutual exclusion; the caller is expected to
      arrange this. }
    with
@@ -3076,7 +3092,8 @@ primop CompactAddWithSharing "compactAddWithSharing#" GenPrimOp
 
 primop CompactSize "compactSize#" GenPrimOp
    Compact# -> State# RealWorld -> (# State# RealWorld, Word# #)
-   { Return the size (in bytes) of the total amount of data in the Compact# }
+   { Return the total capacity (in bytes) of all the compact blocks
+     in the CNF. }
    with
    has_side_effects = True
    out_of_line      = True