fix review issues

Author: wlammen

src/mmdata.c

@@ -180,19 +180,17 @@ vstring g_qsortKey; /* Used by qsortStringCmp; pointer only, do not deallocate *
  * similar, all pushed onto this stack.  When the final operation is executed,
  * and its result is persisted in some variable, the dependency on its
  * temporary operands ceases.  Consequently, they should be freed again.  To
- * automate this operation,  such a stack maintains a __start__ index.  A
- * client saves this value and sets it to the current stack top, then starts
- * pushing dynamically allocated operands on the stack.  After the result is
- * persisted, all entries beginning with the element at index  __start__ are
- * deallocated again, and the stack top is reset to the __start__ value, while
- * the __start__ value is reset to the saved value, to accomodate nesting of
- * this procedure.
+ * automate this operation,  such a stack maintains a `start` index.  A client
+ * saves this value and sets it to the current stack top, then starts pushing
+ * dynamically allocated operands on the stack.  After the result is persisted,
+ * all entries beginning with the element at index  `start` are deallocated
+ * again, and the stack top is reset to the `start` value, while the `start`
+ * value is reset to the saved value, to accommodate nesting of this procedure.
  *
  * This scheme needs a few conditions to be met:
  * - No operand is used in more than one evaluation context;
  * - Operations are executed strictly sequential, or in a nested manner. No two
  *   operations interleave pushing operands.
- *   push operands interleaved
  */
 
 /* Memory pools are used to reduce the number of malloc and alloc calls that
@@ -213,16 +211,27 @@ vstring g_qsortKey; /* Used by qsortStringCmp; pointer only, do not deallocate *
    The pointer to an array always points to element 0 (recast to right size).
 */
 
+/*!
+ * \page doc-todo Improvements in documentation
+ * 
+ * - Revisit the \ref block "block", \ref stack "stack" references to check the
+ *   inserted wording.
+ * - Check what the advantages of __p__ tag are and whether the are better
+ *   replaced with backtick pairs. (\p aParam vs `aParam`)
+ * - Regularly check the warning in \ref pntrString to see whether it still
+ *   holds, or can be made more precise.
+ */
+
 /*!
  * \def MEM_POOL_GROW
  * Amount that \ref memUsedPool and \ref memFreePool grows when it overflows.
  */
-#define MEM_POOL_GROW 1000 /* Amount that a pool grows when it overflows. */
+#define MEM_POOL_GROW 1000
 /*??? Let user set this from menu. */
 /*!
  * \var long poolAbsoluteMax
  * The value is a memory amount in bytes.
- * \n
+ *
  * The \ref suballocator scheme must not hold more memory than is short term
  * useful.  To the operating system all memory in \ref memFreePool appears as
  * allocated, although it is not really in use.  To prevent the system from
@@ -590,14 +599,13 @@ void addToUsedPool(void *ptr)
  * Starting with the last entry in \ref memFreePool, memory held in that pool
  * is returned to the system until all, or at least a sufficient amount is
  * freed again (see \p untilOK).
- * \param[in] untilOK if 1 freeing \ref block "blocks" stops the moment
- *   \ref poolTotalFree gets within the range of \ref poolAbsoluteMax again.
- *   Note that it is not guaranteed that the limit \ref poolAbsoluteMax is
- *   undercut because still too much free memory might be held in the
- *   \ref memUsedPool.
- *   \n
- *   If 0, all \ref memFreePool entries are freed, and the pool itself is
- *   shrunk back to \ref MEM_POOL_GROW size.
+ * \param[in] untilOK
+ *   - if 1 freeing \ref block "blocks" stops the moment \ref poolTotalFree
+ *     gets within the range of \ref poolAbsoluteMax again.  Note that it is
+ *     not guaranteed that the limit \ref poolAbsoluteMax is undercut because
+ *     still too much free memory might be held in the \ref memUsedPool.
+ *   - If 0, all \ref memFreePool entries are freed, and the pool itself is
+ *     shrunk back to \ref MEM_POOL_GROW size.
  */
 void memFreePoolPurge(flag untilOK)
 {

src/mmdata.h

@@ -166,7 +166,7 @@ typedef nmbrString temp_nmbrString;
  * \brief a single \ref pntrString element for use in a \ref stack "stack".
  *
  * These elements are pushed onto and popped off a \ref stack 
- * "stack of temporary data".  All pointer of this type should ONLY refer to
+ * "stack of temporary data".  Pointers of this type should ONLY refer to
  * dynamically allocated memory on the heap.  Special commands support
  * dependency tracking and free all pointers on and after a particular one in
  * such a stack. 
@@ -864,7 +864,6 @@ flag pntrEq(const pntrString *sout, const pntrString *sin);
  *   - the elements of \p g are duplicated.
  *   - a pointer to a NUL byte ("") constant is padded to the right.  Make sure
  *     the referenced memory is never overwritten.
- * \bug a pointer to constant data is added as a writeable void*.
  */
 temp_pntrString *pntrAddElement(const pntrString *g);
 

src/mminou.h

@@ -154,17 +154,9 @@ void printLongLine(const char *line, const char *startNextLine, const char *brea
  * 
  * No timeout is applied while waiting for user input from the console.
  *
- * Detected format errors result in following bug messages:
- *   - 1507: The first read character is NUL
- *   - 1508: line overflow, the last character is not NUL
- *   - 1519: padding of LF failed, or first read character was NUL
- *   - 1521: a NUL in first and second position was read
- *   - 1523: NULL instead of a prompt text when user input is required
- *   - 1525: missing terminating LF, not caused by an EOF.
- *
- *   A bug message need not result in an execution stop.  It is not directed to
- *   the metamath bug function to avoid stacking up calls (bug calling cmdInput
- *   again for scrolling etc.).
+ * A bug message need not result in an execution stop.  It is not directed to
+ * the metamath bug function to avoid stacking up calls (bug calling cmdInput
+ * again for scrolling etc.).
  *
  * \todo clarify recursive call to print2 and the role of backFromCmdInput. 
  * \param[in] stream (not null) source to read the line from.  _stdin_ is

src/mmvstr.h

@@ -458,22 +458,23 @@ temp_vstring right(const char *sin, long n);
  * \fn temp_vstring edit(const char *sin, long control)
  * perform a combination of transformations on \p sin based on the set bits in
  * \p control.  This is an ASCII based transformation.
- *      Bit   Effect
- *      1        Clear parity bits
- *      2        Discard all spaces and tabs
- *      4        Discard characters: CR, LF, FF, ESC, RUBOUT, and NULL
- *      8        Discard leading spaces and tabs
- *      16       Reduce spaces and tabs to one space
- *      32       Convert lowercase to uppercase
- *      64       Convert [ to ( and ] to )
- *      128      Discard trailing spaces and tabs
- *      256      Do not alter characters inside quotes
- *      512      Convert uppercase to lowercase
- *      1024     Tab the line (convert spaces to equivalent tabs)
- *      2048     Untab the line (convert tabs to equivalent spaces)
- *      4096     Convert VT220 screen print frame graphics to -,|,+ characters
- *      8192     Discard CR only (to assist DOS-to-Unix conversion)
- *      16384    Discard trailing spaces, tabs, and LFs
+ *      Bit    |  Effect
+ *      -----  |  ------
+ *      1      |  Clear parity bits
+ *      2      |  Discard all spaces and tabs
+ *      4      |  Discard characters: CR, LF, FF, ESC, RUBOUT, and NULL
+ *      8      |  Discard leading spaces and tabs
+ *      16     |  Reduce spaces and tabs to one space
+ *      32     |  Convert lowercase to uppercase
+ *      64     |  Convert [ to ( and ] to )
+ *      128    |  Discard trailing spaces and tabs
+ *      256    |  Do not alter characters inside quotes
+ *      512    |  Convert uppercase to lowercase
+ *      1024   |  Tab the line (convert spaces to equivalent tabs)
+ *      2048   |  Untab the line (convert tabs to equivalent spaces)
+ *      4096   |  Convert VT220 screen print frame graphics to -,|,+ characters
+ *      8192   |  Discard CR only (to assist DOS-to-Unix conversion)
+ *      16384  |  Discard trailing spaces, tabs, and LFs
  * \param[in] sin (not null) NUL terminated string to convert
  * \param[in] control a combination of set bit requesting the desired
  *   transformation(s)