Added doxygen comments to epicsString.h

modules/libcom/src/misc/epicsString.h

@@ -13,6 +13,12 @@
  *          Mark Rivers, Andrew Johnson, Ralph Lange
  */
 
+/**
+ * \file epicsString.h
+ *
+ * \brief Collection of string utility functions
+ */
+
 #ifndef INC_epicsString_H
 #define INC_epicsString_H
 
@@ -24,20 +30,107 @@
 extern "C" {
 #endif
 
+/** \brief Converts C-style escape sequences to their binary form
+ * 
+ * Copies characters from string to an output buffer and converts C-style escape sequences to 
+ * their binary form.  Since the output string can never be longer than the source, it is legal for 
+ * @p inbuf and @p outbuf to point to the same buffer and @p outsize and @p inlen
+ * be equal, thus performing the character translation in-place.
+ * 
+ * \param outbuf  buffer to copy string to. The resulting string will be zero-terminated as long as 
+ *                @p outsize is non-zero. 
+ * \param outsize length of output buffer not including the null-terminator. 
+ * \param inbuf   buffer to copy from. Null byte terminates the string.
+ * \param inlen   maximum number of characters to copy from input buffer.
+ *
+ * \return  number of characters that were written into output buffer, not counting the null terminator. 
+**/
 LIBCOM_API int epicsStrnRawFromEscaped(char *outbuf,      size_t outsize,
                                            const char *inbuf, size_t inlen);
+
+/** \brief Converts non-printable characters into C-style escape sequences
+ *
+ * Copies characters from the string into a output buffer converting non-printable characters into C-style 
+ * escape sequences.   In-place translations are not allowed since the escaped results will usually be larger
+ * than the input string.
+ *
+ * The following escaped character constants will be used in the output:
+ * \a \b \f \n \r \t \v \\ \’ \" \0
+ * All other non-printable characters appear in form \xHH where HH are two hex digits.
+ * Non-printable characters are determined by the C runtime library’s isprint() function.
+ *
+ * \param outbuf  buffer to copy string to. The resulting string will be zero-terminated as long as 
+ *                @p outsize is non-zero. 
+ * \param outsize length of output buffer not including the null-terminator.
+ * \param inbuf   buffer to copy from. Null byte will not terminates the string.
+ * \param inlen   Number of characters to copy from input buffer.
+ *
+ * \return number of characters that would have been stored in the output buffer if it were large enough, 
+ * or a negative value if dst == src. 
+ *
+ */
 LIBCOM_API int epicsStrnEscapedFromRaw(char *outbuf,      size_t outsize,
                                            const char *inbuf, size_t inlen);
+
+/** \brief Scans string and returns size of output buffer needed to escape that string
+ *
+ * Scans up to \p len characters of the string that may contain non-printable characters, and returns 
+ * the size of the output buffer that would be needed to escape that string. 
+ * This routine is faster than calling epicsStrnEscapedFromRaw with a zero length output buffer; both 
+ * should return the same result.
+ *
+ *\param buf string to scan
+ *\param len length of input string
+ *
+ *\return size of the output buffer that would be needed for converting to escape characters, not 
+ *        including the null terminator. 
+ */
 LIBCOM_API size_t epicsStrnEscapedFromRawSize(const char *buf, size_t len);
+
+/** \brief Does case-insensitive comparison of two strings
+ *
+ * Implements strcmp from the C standard library, except is case insensitive
+ */
 LIBCOM_API int epicsStrCaseCmp(const char *s1, const char *s2);
+
+/** \brief Does case-insensitive comparision of two strings
+ *
+ * Implements strncmp from the C standard library, except is case insensitive
+ */
 LIBCOM_API int epicsStrnCaseCmp(const char *s1, const char *s2, size_t len);
+
+/** \brief Duplicates a string
+ *
+ * Implements strdup from the C standard library.  Calls mallocMustSucceed to allocate memory
+ */
 LIBCOM_API char * epicsStrDup(const char *s);
+
+/** \brief Duplicates a string
+ *
+ * implements strndup from the C standard library. Calls mallocMustSucceed to allocate memory
+ */
 LIBCOM_API char * epicsStrnDup(const char *s, size_t len);
+
+/** \brief Prints escaped version of string
+ *
+ * Prints the contents of its input buffer to given file descriptor,  substituting escape sequences 
+ * for non-printable characters.
+ *
+ * \param fp  File descriptor to print to
+ * \param s   String to print
+ * \param n   Length of string
+ */
 LIBCOM_API int epicsStrPrintEscaped(FILE *fp, const char *s, size_t n);
+    
 #define epicsStrSnPrintEscaped epicsStrnEscapedFromRaw
+
+/** \brief Calculates length of string
+ *
+ * Implements strnlen from the C standard library.    
+ */
 LIBCOM_API size_t epicsStrnLen(const char *s, size_t maxlen);
 
-/** Matches a string against a pattern.
+/** \brief Matches a string against a pattern.
  *
  * Checks if str matches the glob style pattern, which may contain ? or * wildcards.
  * A ? matches any single character.
@@ -49,7 +142,7 @@ LIBCOM_API size_t epicsStrnLen(const char *s, size_t maxlen);
  */
 LIBCOM_API int epicsStrGlobMatch(const char *str, const char *pattern);
 
-/** Matches a string against a pattern.
+/** \brief Matches a string against a pattern.
  *
  * Like epicsStrGlobMatch but with limited string length.
  * If the length of str is less than len, the full string is matched.
@@ -60,11 +153,40 @@ LIBCOM_API int epicsStrGlobMatch(const char *str, const char *pattern);
  */
 LIBCOM_API int epicsStrnGlobMatch(const char *str, size_t len, const char *pattern);
 
+ /** \brief Extract tokens from string
+  * 
+  * Implements strtok_r from the C standard library
+  */
 LIBCOM_API char * epicsStrtok_r(char *s, const char *delim, char **lasts);
+
+/** \brief Calculates a hash of a null-terminated string
+ *
+ * Calculates a hash of a null-terminated string.  Initial seed may be provided which 
+ * permits multiple strings to be combined into a single hash result.
+ *
+ *\param str  null-terminated string
+ *\param seed Optionally provide seed to combine multiple strings in a single hash.  Otherwise
+ *            set to 0.
+ *
+ *\return Hash value for string
+ */    
 LIBCOM_API unsigned int epicsStrHash(const char *str, unsigned int seed);
+
+ /** \brief Calculates a hash of a memory buffer
+  *
+  * Calculates a hash of a memory buffer that may contain null values.  Initial seed may be provided which 
+  * permits multiple buffers to be combined into a single hash result.
+  *
+  *\param str    buffer
+  *\param length size of buffer
+  *\param seed Optionally provide seed to combine multiple buffers in a single hash.  Otherwise
+  *            set to 0.
+  *
+  *\return Hash value for buffer
+  */    
 LIBCOM_API unsigned int epicsMemHash(const char *str, size_t length,
                                          unsigned int seed);
-/** Compare two strings and return a number in the range [0.0, 1.0] or -1.0 on error.
+/** \brief Compare two strings and return a number in the range [0.0, 1.0] or -1.0 on error.
  *
  * Computes a normalized edit distance representing the similarity between two strings.
  *
@@ -75,7 +197,9 @@ LIBCOM_API unsigned int epicsMemHash(const char *str, size_t length,
  */
 LIBCOM_API double epicsStrSimilarity(const char *A, const char *B);
 
-/* dbTranslateEscape is deprecated, use epicsStrnRawFromEscaped instead */
+/** \brief DEPRECATED
+ * \deprecated dbTranslateEscape is deprecated, use epicsStrnRawFromEscaped instead 
+ */
 LIBCOM_API int dbTranslateEscape(char *s, const char *ct);
 
 #ifdef __cplusplus