doc cmdInput1 and dependent(1)

src/mmcmdl.h

@@ -46,6 +46,8 @@ extern flag g_commandEcho; /*!< Echo full command */
 /*!
  * \brief `MEMORY_STATUS` option: Always show memory
  *
+ * Indicates whether the user has turned MEMORY_STATUS on.
+ *
  * If the user issues SET MEMORY_STATUS ON this \ref flag is set to 1.  It is
  * reset to 0 again on a SET MEMORY_STATUS OFF command.  When 1, certain
  * memory de/allocations are monitored - see \ref db3.

src/mmdata.h

@@ -171,6 +171,11 @@ typedef nmbrString temp_nmbrString;
  * 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. 
+=======
+ * These elements are pushed onto and popped off a \ref stack
+ * "stack of temporary data".  Special commands can free all pointers on and
+ * after a particular one in such a stack.
+>>>>>>> upstream/master
  */
 typedef pntrString temp_pntrString;
 
@@ -463,7 +468,9 @@ extern struct nullNmbrStruct g_NmbrNull;
 
 /*!
  * \struct nullPntrStruct
- * describing a \ref block of \ref pntrString containing only the null
+ * \brief Null pntrString -- NULL flags the end of a pntrString
+ *
+ * Describes a \ref block of \ref pntrString containing only the null
  * pointer.  Besides this pointer it is accompanied with a header containing
  * the hidden administrative values of such \ref block "block".
  *
@@ -474,30 +481,31 @@ extern struct nullNmbrStruct g_NmbrNull;
  * void*.  In fact there might be **no** integer type matching a pointer in size.
  */
 struct nullPntrStruct {
-    /*!
-     * An instance of a nullPntrStruct is always standalone and never part of a
-     * larger pool.  Indicated by the fixed value -1.
-     */
-    long poolLoc;
-    /*!
-     * allocated size of the memory block containing the \ref pntrString,
-     * excluding any hidden administrative data.
-     * Note: this is the number of bytes, not elements!  Fixed to the size of a
-     * single void* instance.
-     */
-    long allocSize;
-    /*!
-     * currently used size of the memory block containing the \ref pntrString,
-     * excluding any hidden administrative data.
-     * Note: this is the number of bytes, not elements!  Fixed to the size of a
-     * single pointer element.
-     */
-    long actualSize;
-    /*!
-     * memory for a single void* instance, set and fixed to the null pointer.
-     * A null marks the end of the array.
-     */
-    pntrString nullElement; };
+  /*!
+   * An instance of a nullPntrStruct is always standalone and never part of a
+   * larger pool.  Indicated by the fixed value -1.
+   */
+  long poolLoc;
+  /*!
+   * allocated size of the memory block containing the \ref pntrString,
+   * excluding any hidden administrative data.
+   * Note: this is the number of bytes, not elements!  Fixed to the size of a
+   * single void* instance.
+   */
+  long allocSize;
+  /*!
+   * currently used size of the memory block containing the \ref pntrString,
+   * excluding any hidden administrative data.
+   * Note: this is the number of bytes, not elements!  Fixed to the size of a
+   * single pointer element.
+   */
+  long actualSize;
+  /*!
+   * memory for a single void* instance, set and fixed to the null pointer.
+   * A null marks the end of the array.
+   */
+  pntrString nullElement;
+};
 /*!
  * \var g_PntrNull
  * Global instance of a memory block structured like a
@@ -743,9 +751,10 @@ temp_pntrString *pntrMakeTempAlloc(pntrString *s);
 /**************************************************/
 
 
-/* String assignment - MUST be used to assign vstrings */
 /*!
  * \fn void pntrLet(pntrString **target, const pntrString *source)
+ * String assignment - MUST be used to assign vstrings.
+ *
  * Copies the \ref pntrString elements of \p source to the beginning of a
  * \ref block referenced by \p target.  If necessary, the \p target block is
  * reallocated, and if it is, it gets twice the needed size to account for
@@ -852,9 +861,10 @@ long pntrRevInstr(long start_position, const pntrString *string1,
 /*! 1 if strings are equal, 0 otherwise */
 flag pntrEq(const pntrString *sout, const pntrString *sin);
 
-/* Add a single null string element to a pntrString - faster than pntrCat */
 /*!
  * \fn temp_pntrString *pntrAddElement(const pntrString *g)
+ * Add a single null string element to a pntrString - faster than pntrCat
+ *
  * \param[in] g points to the first element of a NULL terminated array in a
  *   \ref block.  It is assumed it is an array of pointer to \ref vstring.
  * \return a copy of \p g, the terminal NULL replaced with a \ref vstring ""

src/mminou.h

@@ -37,6 +37,7 @@ extern FILE *g_listFile_fp;
 
 /*!
  * \var g_outputToString
+ *
  * Global variable redirecting the output of the function print2 from the
  * console ( = 0) to a string ( = 1).  Initialized to 0 on program start.
  */
@@ -158,10 +159,10 @@ void printLongLine(const char *line, const char *startNextLine, const char *brea
  * This routine interprets some input without returning it to the caller under
  * following two conditions:
  *
- * 1. If scrolling is enabled, a line consisting of a single character b or B
- * indicates the user wants to scroll back through saved pages of output.
- * If it can be served, it is handled within this routine, else the b or B is
- * returned as user input.
+ * 1. If scrolling is enabled, the input is interpreted.  A line consisting of
+ * a single character b or B indicates the user wants to scroll back through
+ * saved pages of output.  This is handled within this routine, as often as
+ * requested and possible.
  *
  * 2. The user hits ENTER only while prompted in top level context.  The empty
  * line is not returned.

src/mmvstr.h

@@ -163,6 +163,43 @@ typedef char* vstring;
  * construction of a final \ref vstring, it is allocated on the heap as usual.
  *
  * If returned by a function, it is already pushed on the \ref tempAllocStack.
+ *
+ * A `temp_vstring` should never be used as the first argument of a `let`.
+ * This code is INCORRECT:
+ *
+ *   temp_vstring foo = left("foobar", 3);
+ *   let(&foo, "bar"); // this will cause a double free
+ *
+ * It is okay (and quite common) to use a temp_vstring as the second argument,
+ * however. It is best not to hold on to the value, though, because the `let`
+ * will free it. This code is INCORRECT:
+ *
+ *   vstring_def(x);
+ *   temp_vstring foobar = cat("foo", "bar");
+ *   let(&x, foobar); // frees foobar
+ *   let(&x, foobar); // dangling reference
+ *
+ * There is a converse problem when `temp_vstring`s are used without `let`:
+ *
+ *   for (int i = 0; i < 100000; i++) {
+ *     vstring_def(x);
+ *     if (strlen(space(i)) == 99999) break;
+ *   }
+ *
+ * We don't need to deallocate the string returned by `space()` directly,
+ * because it returns a `temp_vstring`, but because there is no `let` in
+ * this function, we end up allocating a bunch of temporaries and
+ * effectively get a memory leak. (There is space for about 100
+ * temporaries so this loop will cause a crash.) To solve this problem,
+ * we can either use a dummy `let()` statement in the loop, or call
+ * `freeTempAlloc` directly:
+ *
+ *   for (int i = 0; i < 100000; i++) {
+ *     vstring_def(x);
+ *     if (strlen(space(i)) == 99999) break;
+ *     freeTempAlloc();
+ *   }
+ *
  */
 typedef vstring temp_vstring;