First round of comments while reading the code.

client/X11/xfreerdp.c

@@ -450,6 +450,17 @@ int _xf_error_handler(Display* d, XErrorEvent* ev)
 	return xf_error_handler(d, ev);
 }
 
+/**
+ * Callback given to freerdp_connect() to process the pre-connect operations.
+ * It will parse the command line parameters given to xfreerdp (using freerdp_parse_args())
+ * and fill the rdp_freerdp structure (instance) with the appropriate options to use for the connection.
+ *
+ * @param instance - pointer to the rdp_freerdp structure that contains the connection's parameters, and will
+ * be filled with the appropriate informations.
+ *
+ * @return true if successful. false otherwise.
+ * Can exit with error code XF_EXIT_PARSE_ARGUMENTS if there is an error in the parameters.
+ */
 boolean xf_pre_connect(freerdp* instance)
 {
 	xfInfo* xfi;
@@ -608,6 +619,11 @@ uint32 xf_detect_cpu()
 	return cpu_opt;
 }
 
+/**
+ * Callback given to freerdp_connect() to perform post-connection operations.
+ * It will be called only if the connection was initialized properly, and will continue the initialization based on the
+ * newly created connection.
+ */
 boolean xf_post_connect(freerdp* instance)
 {
 	xfInfo* xfi;

include/freerdp/freerdp.h

@@ -74,9 +74,15 @@ struct rdp_context
 	uint32 paddingC[64 - 38]; /* 38 */
 };
 
+/** Defines the options for a given instance of RDP connection.
+ *  This is built by the client and given to the FreeRDP library to create the connection
+ *  with the expected options.
+ */
 struct rdp_freerdp
 {
-	rdpContext* context; /* 0 */
+	rdpContext* context; /**< (offset 0)
+							  Pointer to a rdpContext structure.
+							  Can be initialized by a call to freerdp_context_new() */
 	uint32 paddingA[16 - 1]; /* 1 */
 
 	rdpInput* input; /* 16 */
@@ -85,12 +91,28 @@ struct rdp_freerdp
 	uint32 paddingB[32 - 19]; /* 19 */
 
 	size_t context_size; /* 32 */
-	pContextNew ContextNew; /* 33 */
-	pContextFree ContextFree; /* 34 */
+
+	pContextNew ContextNew; /**< (offset 33)
+								 Callback for context allocation
+								 Can be set before calling freerdp_context_new() to have it executed after allocation and initialization.
+								 Must be set to NULL if not needed. */
+
+	pContextFree ContextFree; /**< (offset 34)
+								   Callback for context deallocation
+								   Can be set before calling freerdp_context_free() to have it executed before deallocation.
+								   Must be set to NULL if not needed. */
 	uint32 paddingC[48 - 35]; /* 35 */
 
-	pPreConnect PreConnect; /* 48 */
-	pPostConnect PostConnect; /* 49 */
+	pPreConnect PreConnect; /**< (offset 48)
+								 Callback for pre-connect operations.
+								 Can be set before calling freerdp_connect() to have it executed before the actual connection happens.
+								 Must be set to NULL if not needed. */
+
+	pPostConnect PostConnect; /**< (offset 49)
+								   Callback for post-connect operations.
+								   Can be set before calling freerdp_connect() to have it executed after the actual connection has succeeded.
+								   Must be set to NULL if not needed. */
+
 	pAuthenticate Authenticate; /* 50 */
 	pVerifyCertificate VerifyCertificate; /* 51 */
 	uint32 paddingD[64 - 52]; /* 52 */

libfreerdp-core/freerdp.c

@@ -1,4 +1,4 @@
-/**
+/*
  * FreeRDP: A Remote Desktop Protocol Client
  * FreeRDP Core
  *
@@ -28,6 +28,15 @@
 #include <freerdp/freerdp.h>
 #include <freerdp/utils/memory.h>
 
+/** Creates a new connection based on the parameters found in the "instance" parameter (see the structure rdp_freerdp).
+ *  It will use the callbacks registered on the structure to process the pre/post connect operations in order to
+ *  get the have the required behavior whatver the client.
+ *
+ *  @param instance - pointer to a rdp_freerdp structure that contains base information to establish the connection.
+ *  				  On return, this function will be initialized with the new connection's settings.
+ *
+ *  @return true if successful. false otherwise.
+ */
 boolean freerdp_connect(freerdp* instance)
 {
 	rdpRdp* rdp;
@@ -160,6 +169,13 @@ void freerdp_get_version(int* major, int* minor, int* revision)
 		*revision = FREERDP_VERSION_REVISION;
 }
 
+/** Allocator function for a rdp context.
+ *  The function will allocate a rdpRdp structure using rdp_new(), then copy
+ *  its contents to the rdp_freerdp structure given in parameters.
+ *
+ *  @param instance - Pointer to the rdp_freerdp structure that will be initialized with the new context.
+ *                    If the caller has set the ContextNew callback, it will be called at the end of the function.
+ */
 void freerdp_context_new(freerdp* instance)
 {
 	rdpRdp* rdp;
@@ -185,6 +201,14 @@ void freerdp_context_new(freerdp* instance)
 	IFCALL(instance->ContextNew, instance, instance->context);
 }
 
+/** Deallocator function for a rdp context.
+ *  The function will deallocate the resources from the 'instance' parameter that were allocated from a call
+ *  to freerdp_context_new().
+ *  If the ContextFree callback is set in the 'instance' parameter, it will be called before deallocation occurs.
+ *
+ *  @param instance - Pointer to the rdp_freerdp structure that was initialized by a call to freerdp_context_new().
+ *  				  On return, the fields associated to the context are invalid.
+ */
 void freerdp_context_free(freerdp* instance)
 {
 	if (instance->context == NULL)
@@ -204,6 +228,9 @@ uint32 freerdp_error_info(freerdp* instance)
 	return instance->context->rdp->errorInfo;
 }
 
+/** Allocator function for the rdp_freerdp structure.
+ *  @return an allocated structure filled with 0s. Need to be deallocated using freerdp_free()
+ */
 freerdp* freerdp_new()
 {
 	freerdp* instance;
@@ -219,6 +246,10 @@ freerdp* freerdp_new()
 	return instance;
 }
 
+/** Deallocator function for the rdp_freerdp structure.
+ *  @param instance - pointer to the rdp_freerdp structure to deallocate.
+ *                    On return, this pointer is not valid anymore.
+ */
 void freerdp_free(freerdp* instance)
 {
 	if (instance)

libfreerdp-utils/args.c

@@ -1,4 +1,4 @@
-/**
+/** \file
  * FreeRDP: A Remote Desktop Protocol client.
  * Arguments Parsing
  *