improve doc of pntrLet

Author: wlammen

src/mmdata.c

@@ -2468,11 +2468,16 @@ long g_pntrStartTempAllocStack = 0;   /* Where to start freeing temporary alloca
  * \brief a \ref stack "stack" of \ref temp_pntrString.
  *
  * Holds pointers to temporarily allocated data of type \ref temp_pntrString.  Such
- * a \ref stack "stack" is primarily designed to function like a stack for
- * temporary allocated ad hoc operands, as described in \ref stack.  The stack top
- * index is \ref g_pntrTempAllocStackTop, always refering to the next push
- * position.  The \ref g_pntrStartTempAllocStack supports nested operations by
- * indicating where the operands for the upcoming operation start from.
+ * a \ref stack "stack" is primarily designed to operate like one for temporary
+ * allocated ad hoc operands, as described in \ref stack.  The stack top index
+ * is \ref g_pntrTempAllocStackTop, always refering to the next push position.
+ * The \ref g_pntrStartTempAllocStack supports nested operations by indicating
+ * where the operands for the upcoming operation start from.
+ * \attention A \ref pntrString consists of an array of pointers.  These
+ *   pointers may themself refer data that needs a clean up, when the last
+ *   reference  to it disappears (such as deallocating memory for example).
+ *   There is no automatic procedure handling such cases when pointers are
+ *   popped off the stack to be freed.
  * \bug The element type should be temp_pntrString, because a NULL_PNTRSTRING
  *   must not be pushed on the stack.
  */
@@ -2498,6 +2503,8 @@ pntrString *pntrTempAllocStack[M_MAX_ALLOC_STACK];
  *     "block's" header, but the data is still random.
  *   - updates \ref db2
  *   - Exits on out-of-memory
+ * \bug it is unfortunate that the same function is used for opposite
+ *   operations like de-/allocation.
  */
 temp_pntrString *pntrTempAlloc(long size) {
                                 /* pntrString memory allocation/deallocation */

src/mmdata.h

@@ -128,7 +128,7 @@ typedef long nmbrString; /* String of numbers */
  * pointer.  If this array is held in a \ref block, its size can also be
  * determined from its header's administrative data.  Both values must be kept
  * synchronized.  In early phases of memory allocation, when data wasn't
- * assigned yet, this need not hold.
+ * assigned yet, this need not hold, though.
  *
  * To summarize the usages of this type:
  * - If you want to resize the array/stack you need a pointer to element 0.
@@ -728,21 +728,31 @@ temp_pntrString *pntrMakeTempAlloc(pntrString *s);
  * reallocated, and if it is, it gets twice the needed size to account for
  * future growing.  If the \p target block is only partially used after copy it
  * is added to the \ref memUsedPool.  If \p source is empty, the \p target is
- * 
+ * to \ref NULL_PNTRSTRING.
+ * \n
+ * It is assumed that the value persisted in \p target is in fact computed from
+ * temporary operands in \ref pntrTempAllocStack.  All blocks starting with
+ * the element at \ref g_pntrTempAllocStackStart are returned to the
+ * \ref memFreePool.
+ * \attention freed \ref block "blocks" contain \ref pntrString instances.
+ *   See \ref pntrTempAllocStack to learn how this free process can be
+ *   dangerous if no precautions are taken.
  * \param[in,out] target (not null) the address of a pointer pointing to the
  *   first byte of a \ref block receiving the copied elements of \p source.
  * \param[in] source (not null) a pointer to the first \ref pntrString element
  *   in a \ref block, to be copied from.
  * \pre
- *   - source does not contain NULL pointer, but is terminated by one.  This
- *     NULL pointer is not part of the array, but must be present.
+ *   - source does not contain NULL pointerelements , but is terminated by one.
+ *     This final NULL pointer is not part of the array, but must be present.
  *   - the target \ref block does not contain any valuable data.
  * \post
  *   - the \ref block \p target points to is filled with a copy of
  *     \ref pntrString elements \p source points to, padded with a terminal
  *     NULL.
  *   - due to a possible reallocation the pointer \p target points to may
  *     change.
+ *   - The stack pointer of \ref pntrTempAllocStack is reset to
+ *     \ref g_pntrTempAllocStackStart
  *   - updates \ref db3 and \ref poolTotalFree.
  *   - Exit on out-of-memory
  * \bug If the \p target block is full after the copy operation, it is not