doc cmdInput1 and dependent(1) (#75)

* doc cmdInput (1)

* copy preconditions of cmdInput to cmdInput1

* fix description of return in cmdInput

* document the role of CTRL-D in cmdInput

* clarify some points

* better understand hyperlinking in doxygen

* explain cmdIput1, next version

* explain cmdIput1, next version

* explain cmdIput1, next version

* doc log file

* point out copy problems of pointers

* doc addToUsedPool

* fix incorrect usage of memUsedPool in case of full blocks

* clarify post cond. of addToUsedPool

* fix description of memUsedPool

* doc poolFree

* add pre post conditions

* doc poolMalloc and others

* fix doc of getPoolStats

* doc pntrTempAlloc

* fine tuning

* be more precise with temp_pntrString

* improve doc of poolMalloc

* do the best to ref to bug()

* better doc early phase of pntrString allocation

* describe temporary stacks in more detail

* extend description of pntrTempAllocStack

* improve doc of pntrLet

* improve doc of pntrLet

* fix doc of let

* fix spelling errors

* doc pntrAddElement

* doc submit mode in cmdInput1

* finished doc of cmdInput1

* the final edits were not saved, so here they are

* fix review issues

* rm a LF

* add pre to pntrAddElement

* rm more unnecessary LF

* fix dangling conflict marker

* fix indentation

* css for customizing p tags

Co-authored-by: Wolf Lammen <[email protected]>

Author: wlammen

src/metamath.c

@@ -723,16 +723,16 @@ void command(int argc, char *argv[]);
 /*! \fn int main(int argc, char *argv[])
  * \brief entry point of the metamath program
  * \param argc int number of command line parameters
- * \param argv (char*)[] array of \a argc command line parameters, followed by NULL
+ * \param argv (char*)[] array of \p argc command line parameters, followed by NULL
  * \return success 0 else failure
  *
  * Running metamath
  *   ./metamath 'read set.mm' 'verify proof *'
- * will start main with \a argc set to 2, argv[0] to "read set.mm", argv[1]
+ * will start main with \p argc set to 2, argv[0] to "read set.mm", argv[1]
  * to "verify proof *" (both without quotes) and argv[2] to NULL.
  * Returning 0 indicates successful completion, anything else some kind of
- failure.
- * For details see \ref https://en.cppreference.com/w/cpp/language/main_function.
+ * failure.
+ * For details see https://en.cppreference.com/w/cpp/language/main_function.
  */
 int main(int argc, char *argv[]) {
 

src/mmcmdl.h

@@ -47,9 +47,10 @@ 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 \a db3.
+ * memory de/allocations are monitored - see \ref db3.
  */
 extern flag g_memoryStatus;
 

src/mmdata.c

@@ -46,6 +46,12 @@ vstring_def(g_printString);
 long g_commandFileNestingLevel = 0;
 FILE *g_commandFilePtr[MAX_COMMAND_FILE_NESTING + 1];
 vstring g_commandFileName[MAX_COMMAND_FILE_NESTING + 1];
+/*!
+ * \var flag g_commandFileSilent[]
+ * a 1 for a particular \ref g_commandFileNestingLevel suppresses output for
+ * that submit nesting level.  The value for the interactive level
+ * (\ref g_commandFileNestingLevel == 0) is ignored.
+ */
 flag g_commandFileSilent[MAX_COMMAND_FILE_NESTING + 1];
 flag g_commandFileSilentFlag = 0; /* For SUBMIT ... /SILENT */
 
@@ -67,14 +73,16 @@ flag g_quitPrint = 0; /* Flag that user quit the output */
 /*!
  * \var flag localScrollMode
  *
- * temporarily disables prompted scroll (see \a g_scrollMode) until next user
+ * temporarily disables prompted scroll (see \ref g_scrollMode) until next user
  * prompt
  */
 flag localScrollMode = 1; /* 0 = Scroll continuously only till next prompt */
 
 /* Buffer for B (back) command at end-of-page prompt - for future use */
 /*! \var pntrString* backBuffer
- * Buffer for B (back) command at end-of-page prompt.
+ * Buffer for B (back) command at end-of-page prompt.  Although formally a
+ * \ref pntrString is an array of void*, this buffer contains always pointer to
+ * \ref vstring.
  *
  * Some longer text (like help texts for example) provide a page wise display
  * with a scroll option, so the user can move freely back and forth in the
@@ -85,9 +93,10 @@ pntrString_def(backBuffer);
 /*!
  * \var backBufferPos
  *
- * A position within the \a backBuffer.
+ * Number of entries in the \ref backBuffer that are available for repeatedly
+ * scrolling back.  Initialized to 0.
  *
- * \invariant The value 0 requires an empty \a backBuffer.
+ * \invariant The value 0 requires an empty \ref backBuffer.
  */
 long backBufferPos = 0;
 flag backFromCmdInput = 0; /* User typed "B" at main prompt */
@@ -651,7 +660,6 @@ vstring cmdInput(FILE *stream, const char *ask) {
   long i;
 
   while (1) { /* For "B" backup loop */
-// drucke prompt
     if (ask != NULL && !g_commandFileSilentFlag) {
       printf("%s", ask);
 #if __STDC__

src/mmdata.h

@@ -32,7 +32,7 @@ This is an emulation of the string functions available in VMS BASIC.
 /*E*/long db1=0;
 /*!
  * \def INCDB1
- * updates \a db1 if NDEBUG is not defined, is a no operation else.
+ * updates \ref db1 if NDEBUG is not defined, is a no operation else.
  *
  * NDEBUG switches C assert instructions off or on.  So the handling of db1 is
  * aligned with assert().
@@ -46,9 +46,9 @@ This is an emulation of the string functions available in VMS BASIC.
 /*!
  * \def MAX_ALLOC_STACK
  *
- * The number of \a vstring pointers set aside for temporary string evaluation.
- * This number covers the needs of ordinary nested functions but it puts a
- * limit to recurrent calls.
+ * The number of \ref vstring pointers set aside for temporary string
+ * evaluation.  This number covers the needs of ordinary nested functions but
+ * it puts a limit to recurrent calls.
  *
  * The number given here is one greater than actually available.  One entry is
  * reserved for the terminal null pointer marking the top of stack.
@@ -61,20 +61,20 @@ long g_startTempAllocStack = 0;    /* Where to start freeing temporary allocatio
 /*!
  * \brief stack for temporary text.
  *
- * This \ref stack "stack" contains \a vstring pointers holding temporary text
- * like fragments, boilerplate and so on.  The current top of the stack is
- * \a g_tempAllocStackTop.  Nested functions share this stack, each setting
+ * This \ref stack "stack" contains \ref vstring pointers holding temporary
+ * text like fragments, boilerplate and so on.  The current top of the stack is
+ * \ref g_tempAllocStackTop.  Nested functions share this stack, each setting
  * aside its own scope.  The scope of the most nested function begins at index
- * \a g_startTempAllocStack.
+ * \ref g_startTempAllocStack.
  *
- * When a nested function starts execution, it saves \a g_startTempAllocStack
- * and copies the \a g_tempAllocStackTop into it, marking the begin of its own
+ * When a nested function starts execution, it saves \ref g_startTempAllocStack
+ * and copies the \ref g_tempAllocStackTop into it, marking the begin of its own
  * scope of temporaries.  Before returning, both values are restored again.
  *
  * The scope of top level functions begins at index 0
  *.
  * \invariant
- * - The entry at \a g_tempAllocStackTop is NULL.
+ * - The entry at \ref g_tempAllocStackTop is NULL.
  */
 void *tempAllocStack[MAX_ALLOC_STACK];
 
@@ -93,21 +93,21 @@ void freeTempAlloc(void) {
 
 /*!
  * \fn pushTempAlloc(void *mem)
- * \brief pushes a pointer onto the \a tempAllocStack.
+ * \brief pushes a pointer onto the \ref tempAllocStack.
  *
- * In case of a stack overflow \a bug is called.  This function is low level
- * that does not ensure that invariants of \a tempAllocStack are kept.
+ * In case of a stack overflow \ref bugfn "bug" is called.  This function is low level
+ * that does not ensure that invariants of \ref tempAllocStack are kept.
  *
  * \param mem (not null) points to either a non-mutable empty string, or
  *   to allocated memory.  Its contents need not be valid yet, although it is
  *   recommended to point to a non-NUL character.
  * \pre
  *   The stack must not be full.
  * \post
- *   If not full, \a mem is added on top of \a tempAllocStack, and
- *   \a g_tempAllocStackTop is increased.  This function
+ *   If not full, \p mem is added on top of \ref tempAllocStack, and
+ *   \ref g_tempAllocStackTop is increased.  This function
  *   does not ensure a NULL pointer follows the pushed pointer.  Statistics in
- *   \a db1 is not updated.
+ *   \ref db1 is not updated.
  * \warning
  *   In case of stack overflow, the caller is not notified and a memory leak
  *   is likely.
@@ -127,19 +127,20 @@ static void pushTempAlloc(void *mem)
 /*!
  * \fn tempAlloc(long size)
  *
- * \brief allocates memory for size bytes and pushes it onto the \a tempAllocStack
+ * \brief allocates memory for size bytes and pushes it onto the
+ *   \ref tempAllocStack
  *
  * This low level function does NOT initialize the allocated memory.  If the
- * allocation on the heap fails, \a bug is called.  The statistic value \a db1
- * is updated.
+ * allocation on the heap fails, \ref bugfn "bug" is called.  The statistic
+ * value \ref db1 is updated.
  *
  * \param size (> 0) number of bytes to allocate on the heap.  If the memory is
  *   intended to hold NUL terminated text, then size must account for the final
  *   NUL character, too.
  * \pre
- *   The \a tempAllocStack must not be full.
+ *   The \ref tempAllocStack must not be full.
  * \post
- *   The top of \a tempAllocStack addresses memory at least the size of the
+ *   The top of \ref tempAllocStack addresses memory at least the size of the
  *   submitted parameter.
  * \warning
  *   In case of stack overflow, the caller is not notified and a memory leak