More comments in common/

1 files changed, 68 insertions, 2 deletions

diff --git a/common/eurephia_nullsafe.h b/common/eurephia_nullsafe.h
index 531d6f2..55a9148 100644
--- a/common/eurephia_nullsafe.h
+++ b/common/eurephia_nullsafe.h
@@ -20,15 +20,81 @@
  *  along with this program; if not, write to the Free Software
  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
  *
-*/
+ */
+
+/**
+ * @file   eurephia_nullsafe.h
+ * @author David Sommerseth <dazo@users.sourceforge.net>
+ * @date   2008-08-06
+ *
+ * @brief standard C string functions, which is made NULL safe by checking
+ *        if input value is NULL before performing the action.
+ *
+ */
 
 #ifndef   	EUREPHIA_NULLSAFE_H_
 #define    	EUREPHIA_NULLSAFE_H_
 
+/**
+ * atoi() wrapper.  Converts any string into a integer
+ *
+ * @param str Input string
+ *
+ * @return Returns integer
+ */
 #define atoi_nullsafe(str) (str != NULL ? atoi(str) : 0)
+
+
+/**
+ * strdup() wrapper.  Duplicates the input string.
+ *
+ * @param str Input string to be duplicated
+ *
+ * @return Returns a pointer to the duplicate (char *) on success, NULL otherwise.
+ * If input was NULL, NULL is returned.
+ */
 #define strdup_nullsafe(str) (str != NULL ? strdup(str) : NULL)
+
+
+/**
+ * strlen() wrapper.  Returns the length of a string
+ *
+ * @param str Input string
+ *
+ * @return Returns int with length of string.  If input is NULL, it returns 0.
+ */
 #define strlen_nullsafe(str) (str != NULL ? strlen(str) : 0)
-#define free_nullsafe(str) if( str != NULL ) { free(str); str = NULL;}
+
+
+/**
+ * free() wrapper.  Frees memory allocated by malloc() or calloc().  It also sets the
+ * input pointer to NULL on success.
+ *
+ * @param ptr Pointer to the memory region being freed.
+ *
+ */
+#define free_nullsafe(ptr) if( ptr != NULL ) { free(ptr); ptr = NULL; }
+
+
+/**
+ * Function which will return a default string value if no input data was provided.
+ *
+ * @param str     Input string
+ * @param defstr  Default string
+ *
+ * @return Returns the pointer to the input string if the string length > 0.  Otherwise it
+ * will return a pointer to the default string.
+ */
 #define defaultValue(str, defstr) (strlen_nullsafe(str) == 0 ? defstr : str)
+
+
+/**
+ * Function which will return a default integer value if no input data was provided.
+ *
+ * @param ival   input integer value
+ * @param defval default integer value
+ *
+ * @return Returns the ival value if it is > 0, otherwise defval value is returned.
+ */
 #define defaultIntValue(ival, defval) (ival == 0 ? defval : ival)
 #endif 	    /* !EUREPHIA_NULLSAFE_H_ */