doc update

Author: wlammen

src/mmfatl.c

@@ -17,6 +17,10 @@
  *   -DINLINE=inline -DTEST_ENABLE -c -o mmfatl.o ../src/mmfatl.c
  *
  * This should not produce an error or a warning.
+ *
+ * If you have Doxygen installed the parameter -d of the build.sh script
+ * generates a hyperlinked documentation from the comments both here and in the
+ * header file.
  */
 
 #include <limits.h>
@@ -91,9 +95,11 @@ struct Buffer {
 static struct Buffer buffer;
 
 /*!
+ * \brief initilize and empty the message buffer.
+ *
  * We do not rely on any initialization during program start.  Instead we
  * assume the worst case, a corrupted pointer overwrote the buffer.  So we
- * initialize it again immediately before use.
+ * initialize it immediately before use.
  * \pre the ellipsis appended to the writeable portion of the buffer must
  *   terminate with a LF, so printing a buffer in overflow state will keep
  *   a command prompt in a new line after program exit.
@@ -111,6 +117,8 @@ static void initBuffer(struct Buffer* buffer) {
 }
 
 /*!
+ * \brief checking the message buffer for emptiness
+ *
  * \param buffer [const, not null] the buffer to check for emptiness.
  * \return true, iff the \ref buffer is in its initial state.
  * \pre \ref initBuffer was called
@@ -120,6 +128,8 @@ inline static bool isBufferEmpty(struct Buffer const* buffer) {
 }
 
 /*!
+ * \brief last character in the message buffer
+ *
  * Get the last stored character in the buffer.  Discarded characters due to
  * overflow are ignored.  A returned NUL indicates the buffer is empty.
  * \param buffer [const, not null] the buffer to investigate.
@@ -131,6 +141,8 @@ static char getLastBufferedChar(struct Buffer const* buffer) {
 }
 
 /*!
+ * \brief check whether the buffer is overflown
+ *
  * \param buffer [const, not null] the buffer to check for overflow.
  * \return true, iff the current contents exceeds the capacity of the
  *   \ref buffer, so at least the terminating \ref NUL is cut off, maybe more.
@@ -141,6 +153,8 @@ inline static bool isBufferOverflow(struct Buffer const* buffer) {
 }
 
 /*!
+ * \brief modes to append text to the message buffer
+ *
  * used to indicate whether \ref MMFATL_PH_PREFIX is a normal character, or
  * an escape character in a format string.
  */
@@ -150,6 +164,8 @@ enum SourceType {
 };
 
 /*!
+ * \brief append text to the current contents of the message buffer
+ *
  * append characters to the current end of the buffer from a string until a
  * terminating \ref NUL, or optionally a placeholder is encountered, or the
  * buffer overflows.
@@ -170,6 +186,8 @@ static unsigned appendText(char const* source, enum SourceType type,
 }
 
 /*!
+ * \brief state of the parser scanning a formatted message in printf style
+ *
  * A simple grammar scheme allows inserting data in a prepared general message.
  * The scheme is a downgrade of the C format string.  Allowed are only
  * placeholders %s and %u that are replaced with given data.  The percent sign
@@ -211,6 +229,8 @@ struct ParserState {
 static struct ParserState state;
 
 /*!
+ * \brief initializes the parser state (but not the associated message buffer!)
+ *
  * initializes \ref state.
  * \post establish the invariant in state
  * \param state [not null] the struct \ref ParserState to initialize.
@@ -224,6 +244,8 @@ static void initState(struct ParserState* state, struct Buffer* buffer) {
 }
 
 /*!
+ * \brief converting an unsigned to a string of decimal numbers
+ *
  * converts an unsigned to a sequence of decimal digits representing its value.
  * The value range is known to be at least 2**32 on contemporary hardware, but
  * C99 guarantees just 2**16.  We support unsigned in formatted error output
@@ -260,7 +282,10 @@ static char const* unsignedToString(unsigned value) {
   return digits + ofs;
 }
 
-/*! reflect a possible buffer overflow in the parser state
+/*!
+ * \brief update the parser state in case of message buffer overflow
+ *
+ * reflect a possible buffer overflow in the parser state
  * \param state [not null] ParserState object being updated in case of
  *   overflow
  * \return false in case of overflow
@@ -275,6 +300,8 @@ static bool checkOverflow(struct ParserState* state) {
 }
 
 /*!
+ * \brief copy a portion of text verbatim to the message buffer
+ *
  * copy text verbatim from a format string to the message buffer, until either
  * the format ends, or a placeholder is encountered.
  * \param state struct ParserState* parser state going to be handled and updated
@@ -290,6 +317,8 @@ static void handleText(struct ParserState* state) {
 }
 
 /*!
+ * \brief handle a placeholder in a formatted message
+ *
  * A format specifier is a two character combination, where a placeholder
  * character \ref MMFATL_PH_PREFIX is followed by an alphabetic character
  * designating a type.  A placeholder is substituted by the next argument in
@@ -342,6 +371,8 @@ static void handleSubstitution(struct ParserState* state) {
 }
 
 /*!
+ * \brief convert a formatted message to human readable text
+ *
  * parses the submitted format string, replacing each placeholder with one of
  * the values in member args of \ref state, and appends the result to the
  * current contents of \ref buffer.
@@ -386,6 +417,8 @@ char const* getFatalErrorPlaceholderToken(
 }
 
 /*!
+ * \brief get the message buffer instance
+ *
  * gets the instance of Buffer to use with this interface (currently a global
  * singleton).  The returned instance is not guaranteed to be initialized.
  * \return [not null] a pointer to the Buffer instance
@@ -395,6 +428,8 @@ inline static struct Buffer* getBufferInstance(void) {
 }
 
 /*!
+ * \brief get the parser state instance
+ *
  * gets the instance of ParserState to use with this interface (currently a
  * global singleton).  The returned instance is not guaranteed to be
  * initialized.

src/mmfatl.h

@@ -14,14 +14,18 @@
  * \file mmfatl.h
  * \brief supports generating of fatal error messages
  *
- * part of the application's infrastructure
+ * In a sort of 3-tier architecture consisting of resource/configuration/data
+ * management, operation logic and algorithms, and presentation layer (or user
+ * interface), this code is interfacing the operating system on the
+ * lowest infrastructure (resource) layer.
  *
  * Rationale
  * =========
  *
  * When a fatal error occurs, the internal structures of a program may be
  * corrupted to the point that recovery is impossible.  The program exits
- * immediately, but hopefully still displays a diagnostic message.
+ * immediately with a failure code, but hopefully still displays a diagnostic
+ * message.
  *
  * To display this final message, we restrict its code to very basic,
  * self-contained routines, independent of the rest of the program to the
@@ -31,7 +35,7 @@
  * in a corrupted or memory-tight environment is minimized.  This is to the
  * detriment of flexibility, in particular, support for dynamic behavior is
  * limited.  Many Standard C library functions like printf MUST NOT be called
- * when heap problems arise, since they use it internally.  GNU tags such
+ * when heap problems arise, since they rely on it internally.  GNU tags such
  * functions as 'AS-Unsafe heap' in their documentation (libc.pdf).
  *
  * Often it is sensible to embed details in a diagnosis message.  Placeholders
@@ -50,22 +54,30 @@
 /***   Export basic features of the fatal error message processing   ***/
 
 
-/*! the size a fatal error message including the terminating NUL character can
+/*!
+ * \brief size of a text buffer used to construct a message
+ *
+ * the size a fatal error message including the terminating NUL character can
  * assume without truncation. Must be in the range of an int.
  */
 enum {
   MMFATL_MAX_MSG_SIZE = 1024,
 };
 
-/*! the character sequence appended to a truncated fatal error message due to
- * a buffer overflow, so its reader is aware a displayed text is incomplete.
- * The ellipsis is followed by a line feed to ensure even an overflown message
- * ends with one.  This is to separate a message from the command prompt
- * following an exit.
+/*!
+ * \brief ASCII text sequence indicating truncated text
+ *
+ * the character sequence appended to a truncated fatal error message due to a
+ * buffer overflow, so its reader is aware a displayed text is incomplete.  The
+ * ellipsis is followed by a line feed to ensure even an overflown message ends
+ * with one.  This is to separate a message from the command prompt following
+ * an exit.
  */
 #define MMFATL_ELLIPSIS "...\n"
 
 /*!
+ * \brief ASCII characters used for placeholder tokens, printf style
+ *
  * supported value types of a two character placeholder token in a format
  * string.  The first character of a placeholder is always an escape
  * character \ref MMFATL_PH_PREFIX, followed by one of the type characters
@@ -79,7 +91,7 @@ enum {
  * in this particular case.
  */
 enum fatalErrorPlaceholderType {
-   //! escape character marking a placeholder
+   //! escape character marking a placeholder, followed by a type character
   MMFATL_PH_PREFIX = '%',
   //! type character marking a placeholder for a string
   MMFATL_PH_STRING = 's',
@@ -152,13 +164,13 @@ extern void fatalErrorInit(void);
  *   correct placeholder token.
  *
  *   NULL is equivalent to an empty format string, and supported both as a
- *   \ref format string and as a parameter for a string placeholder, to
+ *   \p format string and as a parameter for a string placeholder, to
  *   enhance robustness.
  *
  *   It is recommended to let the message end with a LF character, so a command
  *   prompt following it is displayed on a new line.  If it is missing
- *   \ref fatalErrorPrintAndExit will supply one, but relying on this adds to
- *   unnecessary steps under severe conditions.
+ *   \ref fatalErrorPrintAndExit will supply one, but relying on this adds an
+ *   unnecessary correction under severe conditions.
  *   
  * 
  * The \p format is followed by a possibly empty list of paramaters substituted
@@ -190,7 +202,21 @@ extern bool fatalErrorPush(char const* format, ...);
  * \brief display buffer contents and exit program with code EXIT_FAILURE.
  * 
  * This function does not return.
- * 
+ *
+ * A NUL terminated message has been prepared in an internal buffer using a
+ * sequence of \ref fatalErrorPush.  This function writes this message to
+ * stderr (by default tied to the terminal screen like stdout), and exits the
+ * program afterwards, indicating a failure to the operating system.
+ *
+ * A line feed is appended to a prepared non-empty message if it is not its
+ * last character.  This keeps the message and a command prompt following the
+ * exit on separare lines.  It is recommended to avoid this corrective
+ * measure and supply a terminating line feed as part of the message.
+ *
+ * It is possible to call this function without preparing a message.  In this
+ * case nothing is written to stderr, and the program just exits with a failure
+ * code.
+ *
  * \pre \ref fatalErrorInit has initialized the internal error message
  *   buffer, possibly followed by a sequence of \ref fatalErrorPush
  *   filling it with a message.
@@ -203,28 +229,43 @@ extern bool fatalErrorPush(char const* format, ...);
  *   stderr to, say, a log file, the error message is displayed to the user on
  *   his terminal.
  * \warning previous versions of Metamath returned the exit code 1.  Many
- *   implementations define EXIT_FAILURE to this very value, but that is not
- *   mandated by the C11 standard.  In fact, some systems may interpret 1 as a
- *   success code, so EXIT_FAILURE is more appropriate.
+ *   systemss define EXIT_FAILURE to this very value, but that is not mandated
+ *   by the C11 standard.  In fact, some systems may interpret 1 as a success
+ *   code, so EXIT_FAILURE is more appropriate.
  */
 extern void fatalErrorPrintAndExit(void);
 
 /*!
- * convenience function, covering a sequence of \ref fatalErrorInit,
+ * \brief standard error reporting and program exit with failure code.
+ *
+ * Convenience function, covering a sequence of \ref fatalErrorInit,
  * \ref fatalErrorPush and \ref fatalErrorPrintAndExit in succession.  This
  * function does not return.
  *
+ * If an error location is given, it is printed first, followed by any
+ * non-empty message.  A line feed is padded to the right of the message if it
+ * is missing.  This is to keep a following command prompt on a new line.  It
+ * is recommended to avoid this corrective measure and supply a line feed as
+ * part of the message.
+ *
+ * If all parameters are NULL or 0, no message is printed, not even the
+ * automatically supplied line feed, and this function just exits the program
+ * with an error code.  If possible use \ref fatalErrorPrintAndExit directly
+ * instead.
+ *
  * \param file [null] filename of code responsible for calling this function,
- *   suitable for macro __FILE__.  Part of an error location.
+ *   suitable for macro __FILE__.  Part of an error location.  Ignored in case
+ *   of NULL.
  * \param line [unsigned] if greater 0, interpreted as a line number, where
  *   a call to this function is initiated, suitable for macro __LINE__.
  *   Part of an error location.
- * \param msgWithPlaceholders the error message to display.  This message
- *   may include placeholders, in which case it must be followed by more
- *   parameters, corresponding to the values to replace the placeholders.
- *   These values must match in type that of the placeholders, and their
- *   number must be enough (can be more) to cover all placeholders.  The
- *   details of this process is explained in \ref fatalErrorPush.
+ * \param msgWithPlaceholders [null] the error message to display.  This
+ *   message may include placeholders in printf style, in which case it must be
+ *   followed by more parameters, corresponding to the values replacing
+ *   placeholders.  These values must match in type that of the placeholders,
+ *   and their number must be enough (can be more) to cover all placeholders.
+ *   The details of this process is explained in \ref fatalErrorPush.  Ignored
+ *   if NULL.
  * \post the program exits with EXIT_FAILURE return code, after writing the
  *   error location and message to stderr.
  */