Merge pull request #602 from littlejawa/comments

Adding comments for doxygen doc

libfreerdp-utils/list.c

@@ -1,4 +1,4 @@
-/**
+/*
  * FreeRDP: A Remote Desktop Protocol Client
  * Double-linked List Utils
  *

libfreerdp-utils/memory.c

@@ -1,4 +1,4 @@
-/**
+/*
  * FreeRDP: A Remote Desktop Protocol Client
  * Memory Utils
  *
@@ -25,7 +25,12 @@
 
 /**
  * Allocate memory.
- * @param size
+ * This function is used to secure a malloc call.
+ * It verifies its return value, and logs an error if the allocation failed.
+ *
+ * @param size - number of bytes to allocate. If the size is < 1, it will default to 1.
+ *
+ * @return a pointer to the allocated buffer. NULL if the allocation failed.
  */
 
 void* xmalloc(size_t size)
@@ -48,9 +53,13 @@ void* xmalloc(size_t size)
 
 /**
  * Allocate memory initialized to zero.
- * @param size
+ * This function is used to secure a calloc call.
+ * It verifies its return value, and logs an error if the allocation failed.
+ *
+ * @param size - number of bytes to allocate. If the size is < 1, it will default to 1.
+ *
+ * @return a pointer to the allocated and zeroed buffer. NULL if the allocation failed.
  */
-
 void* xzalloc(size_t size)
 {
 	void* mem;
@@ -71,8 +80,13 @@ void* xzalloc(size_t size)
 
 /**
  * Reallocate memory.
- * @param ptr
- * @param size
+ * This function is used to secure a realloc call.
+ * It verifies its return value, and logs an error if the allocation failed.
+ *
+ * @param ptr - pointer to the buffer that needs reallocation. This can be NULL, in which case a new buffer is allocated.
+ * @param size - number of bytes to allocate. If the size is < 1, it will default to 1.
+ *
+ * @return a pointer to the reallocated buffer. NULL if the allocation failed (in which case the 'ptr' argument is untouched).
  */
 
 void* xrealloc(void* ptr, size_t size)
@@ -92,7 +106,10 @@ void* xrealloc(void* ptr, size_t size)
 
 /**
  * Free memory.
- * @param mem
+ * This function is used to secure a free call.
+ * It verifies that the pointer is valid (non-NULL) before trying to deallocate it's buffer.
+ *
+ * @param ptr - pointer to a buffer that needs deallocation. If ptr is NULL, nothing will be done (no segfault).
  */
 
 void xfree(void* ptr)
@@ -103,8 +120,14 @@ void xfree(void* ptr)
 
 /**
  * Duplicate a string in memory.
- * @param str
- * @return
+ * This function is used to secure the strdup function.
+ * It will allocate a new memory buffer and copy the string content in it.
+ * If allocation fails, it will log an error.
+ *
+ * @param str - pointer to the character string to copy. If str is NULL, nothing is done.
+ *
+ * @return a pointer to a newly allocated character string containing the same bytes as str.
+ * NULL if an allocation error occurred, or if the str parameter was NULL.
  */
 
 char* xstrdup(const char* str)
@@ -127,9 +150,14 @@ char* xstrdup(const char* str)
 }
 
 /**
- * Duplicate a string in memory.
- * @param wstr
- * @return
+ * Duplicate a wide string in memory.
+ * This function is used to secure a call to wcsdup.
+ * It verifies the return value, and logs a message if an allocation error occurred.
+ *
+ * @param wstr - pointer to the wide-character string to duplicate. If wstr is NULL, nothing will be done.
+ *
+ * @return a pointer to the newly allocated string, containing the same data as wstr.
+ * NULL if an allocation error occurred (or if wstr was NULL).
  */
 
 wchar_t* xwcsdup(const wchar_t* wstr)
@@ -157,6 +185,16 @@ wchar_t* xwcsdup(const wchar_t* wstr)
 	return mem;
 }
 
+/**
+ * Create an uppercase version of the given string.
+ * This function will duplicate the string (using xstrdup()) and change its content to all uppercase.
+ * The original string is untouched.
+ *
+ * @param str - pointer to the character string to convert. This content is untouched by the function.
+ *
+ * @return pointer to a newly allocated character string, containing the same content as str, converted to uppercase.
+ * NULL if an allocation error occured.
+ */
 char* xstrtoup(const char* str)
 {
 	char* out;
@@ -171,8 +209,6 @@ char* xstrtoup(const char* str)
 			c = toupper((unsigned char)*p);
 			*p++ = (char)c;
 		}
-		return out;
 	}
-	else
-		return NULL;
+	return out;
 }

libfreerdp-utils/mutex.c

@@ -1,4 +1,4 @@
-/**
+/*
  * FreeRDP: A Remote Desktop Protocol Client
  * Mutex Utils
  *
@@ -28,6 +28,22 @@
 #define freerdp_mutex_t pthread_mutex_t
 #endif
 
+/**
+ * Mutex are used to prevent concurrent accesses to specific portions of code.
+ * This funciton and the other freerdp_mutex_*() function are defining a portable API
+ * to get mutex for both Windows and Linux, where the lower level implementation is very different.
+ *
+ * This function creates a new freerdp_mutex object.
+ * Use freerdp_mutex_lock() to get exclusive ownership of the mutex, and lock a given (protected) portion of code.
+ * Use freerdp_mutex_unlock() to release your ownership on a mutex.
+ * Use freerdp_mutex_free() to release the resources associated with the mutex when it is no longer needed.
+ *
+ * @return a freerdp_mutex pointer. This should be considered opaque, as the implementation is platform dependent.
+ * NULL is returned if an allocation or initialization error occurred.
+ *
+ * @see pthread documentation for Linux implementation of mutexes
+ * @see MSDN http://msdn.microsoft.com/en-us/library/windows/desktop/ms682411%28v=vs.85%29.aspx for Windows implementation
+ */
 freerdp_mutex freerdp_mutex_new(void)
 {
 #ifdef _WIN32
@@ -37,11 +53,18 @@ freerdp_mutex freerdp_mutex_new(void)
 #else
 	freerdp_mutex_t* mutex;
 	mutex = xnew(freerdp_mutex_t);
-	pthread_mutex_init(mutex, 0);
+	if (mutex)
+		pthread_mutex_init(mutex, 0);
 	return mutex;
 #endif
 }
 
+/**
+ * This function is used to deallocate all resources associated with a freerdp_mutex object.
+ *
+ * @param mutex [in]	- Pointer to the mutex that needs to be deallocated.
+ * 						  On return, this object is not valid anymore.
+ */
 void freerdp_mutex_free(freerdp_mutex mutex)
 {
 #ifdef _WIN32
@@ -52,6 +75,15 @@ void freerdp_mutex_free(freerdp_mutex mutex)
 #endif
 }
 
+/**
+ * Use this function to get exclusive ownership of the mutex.
+ * This should be called before entering a portion of code that needs to be protected against concurrent accesses.
+ * Use the freerdp_mutex_unlock() call to release ownership when you leave this protected code.
+ *
+ * @param mutex [in]	- An initialized freerdp_mutex object, as returned from a call to freerdp_mutex_new().
+ *						  This function will suspend the running thread when called, until the mutex is available.
+ *						  Only one thread at a time will be allowed to continue execution.
+ */
 void freerdp_mutex_lock(freerdp_mutex mutex)
 {
 #ifdef _WIN32
@@ -61,6 +93,13 @@ void freerdp_mutex_lock(freerdp_mutex mutex)
 #endif
 }
 
+/**
+ * Use this function to release your ownership on a mutex.
+ * This should be called when leaving a portion of code that needs to be protected against concurrent accesses.
+ * DO NOT use this call on a mutex that you do not own. See freerdp_mutex_lock() for getting ownership on a mutex.
+ *
+ * @param mutex [in]	- Pointer to a mutex that was locked by a call to freerdp_mutex_lock().
+ */
 void freerdp_mutex_unlock(freerdp_mutex mutex)
 {
 #ifdef _WIN32