Add doxygen documentation support.

    Adds automagically generating libvncserver/libvncclient API
    documentation using doxygen. This gives a nice overview on both APIs,
    include dependencies and function call/caller dependencies.

    TODO: Modify all the explaining comments in the .c files for use with
          doxygen as well.

    This patch only changes comments, no functional changes at all!

Signed-off-by: Christian Beier <dontmind@freeshell.org>

1 files changed, 43 insertions, 29 deletions

diff --git a/rfb/rfbclient.h b/rfb/rfbclient.h
index 1edd32e..f3bd11d 100644
--- a/rfb/rfbclient.h
+++ b/rfb/rfbclient.h
@@ -1,6 +1,11 @@
 #ifndef RFBCLIENT_H
 #define RFBCLIENT_H
 
+/**
+ * @defgroup libvncclient_api LibVNCClient API Reference
+ * @{
+ */
+
 /*
  *  Copyright (C) 2000, 2001 Const Kaplinsky.  All Rights Reserved.
  *  Copyright (C) 2000 Tridia Corporation.  All Rights Reserved.
@@ -22,8 +27,8 @@
  *  USA.
  */
 
-/*
- * vncviewer.h
+/**
+ * @file rfbclient.h
  */
 
 #include <stdio.h>
@@ -72,7 +77,7 @@ extern "C"
 {
 #endif
 
-/* vncrec */
+/** vncrec */
 
 typedef struct {
   FILE* file;
@@ -81,7 +86,7 @@ typedef struct {
   rfbBool doNotSleep;
 } rfbVNCRec;
 
-/* client data */
+/** client data */
 
 typedef struct rfbClientData {
 	void* tag;
@@ -89,7 +94,7 @@ typedef struct rfbClientData {
 	struct rfbClientData* next;
 } rfbClientData;
 
-/* app data (belongs into rfbClient?) */
+/** app data (belongs into rfbClient?) */
 
 typedef struct {
   rfbBool shareDesktop;
@@ -107,14 +112,14 @@ typedef struct {
   int qualityLevel;
   rfbBool enableJPEG;
   rfbBool useRemoteCursor;
-  rfbBool palmVNC;  /* use palmvnc specific SetScale (vs ultravnc) */
-  int scaleSetting; /* 0 means no scale set, else 1/scaleSetting */
+  rfbBool palmVNC;  /**< use palmvnc specific SetScale (vs ultravnc) */
+  int scaleSetting; /**< 0 means no scale set, else 1/scaleSetting */
 } AppData;
 
-/* For GetCredentialProc callback function to return */
+/** For GetCredentialProc callback function to return */
 typedef union _rfbCredential
 {
-  /* X509 (VeNCrypt) */
+  /** X509 (VeNCrypt) */
   struct
   {
     char *x509CACertFile;
@@ -122,7 +127,7 @@ typedef union _rfbCredential
     char *x509ClientCertFile;
     char *x509ClientKeyFile;
   } x509Credential;
-  /* Plain (VeNCrypt), MSLogon (UltraVNC) */
+  /** Plain (VeNCrypt), MSLogon (UltraVNC) */
   struct
   {
     char *username;
@@ -162,7 +167,7 @@ typedef struct _rfbClient {
 
 	const char* programName;
 	char* serverHost;
-	int serverPort; /* if -1, then use file recorded by vncrec */
+	int serverPort; /**< if -1, then use file recorded by vncrec */
 	rfbBool listenSpecified;
 	int listenPort, flashPort;
 
@@ -170,7 +175,7 @@ typedef struct _rfbClient {
 		int x, y, w, h;
 	} updateRect;
 
-	/* Note that the CoRRE encoding uses this buffer and assumes it is big enough
+	/** Note that the CoRRE encoding uses this buffer and assumes it is big enough
 	   to hold 255 * 255 * 32 bits -> 260100 bytes.  640*480 = 307200 bytes.
 	   Hextile also assumes it is big enough to hold 16 * 16 * 32 bits.
 	   Tight encoding assumes BUFFER_SIZE is at least 16384 bytes. */
@@ -221,7 +226,7 @@ typedef struct _rfbClient {
 	 * Variables for the ``tight'' encoding implementation.
 	 */
 
-	/* Separate buffer for compressed data. */
+	/** Separate buffer for compressed data. */
 #define ZLIB_BUFFER_SIZE 30000
 	char zlib_buffer[ZLIB_BUFFER_SIZE];
 
@@ -236,7 +241,7 @@ typedef struct _rfbClient {
 	uint8_t tightPrevRow[2048*3*sizeof(uint16_t)];
 
 #ifdef LIBVNCSERVER_HAVE_LIBJPEG
-	/* JPEG decoder state. */
+	/** JPEG decoder state. */
 	rfbBool jpegError;
 
 	struct jpeg_source_mgr* jpegSrcManager;
@@ -250,7 +255,7 @@ typedef struct _rfbClient {
 	/* cursor.c */
 	uint8_t *rcSource, *rcMask;
 
-	/* private data pointer */
+	/** private data pointer */
 	rfbClientData* clientData;
 
 	rfbVNCRec* vncRec;
@@ -269,7 +274,7 @@ typedef struct _rfbClient {
 	SoftCursorUnlockScreenProc SoftCursorUnlockScreen;
 	GotFrameBufferUpdateProc GotFrameBufferUpdate;
 	FinishedFrameBufferUpdateProc FinishedFrameBufferUpdate;
-	/* the pointer returned by GetPassword will be freed after use! */
+	/** the pointer returned by GetPassword will be freed after use! */
 	GetPasswordProc GetPassword;
 	MallocFrameBufferProc MallocFrameBuffer;
 	GotXCutTextProc GotXCutText;
@@ -278,7 +283,7 @@ typedef struct _rfbClient {
 	GotCursorShapeProc GotCursorShape;
 	GotCopyRectProc GotCopyRect;
 
-	/* Which messages are supported by the server
+	/** Which messages are supported by the server
 	 * This is a *guess* for most servers.
 	 * (If we can even detect the type of server)
 	 *
@@ -288,18 +293,18 @@ typedef struct _rfbClient {
 	 */
 	rfbSupportedMessages supportedMessages;
 
-	/* negotiated protocol version */
+	/** negotiated protocol version */
 	int major, minor;
 
-	/* The selected security types */
+	/** The selected security types */
 	uint32_t authScheme, subAuthScheme;
 
 #ifdef LIBVNCSERVER_WITH_CLIENT_TLS
-	/* The TLS session for Anonymous TLS and VeNCrypt */
+	/** The TLS session for Anonymous TLS and VeNCrypt */
 	gnutls_session_t tlsSession;
 #endif
 
-	/* To support security types that requires user input (except VNC password
+	/** To support security types that requires user input (except VNC password
 	 * authentication), for example VeNCrypt and MSLogon, this callback function
 	 * must be set before the authentication. Otherwise, it implicates that the
 	 * caller application does not support it and related security types should
@@ -307,18 +312,18 @@ typedef struct _rfbClient {
 	 */
 	GetCredentialProc GetCredential;
 
-	/* The 0-terminated security types supported by the client.
+	/** The 0-terminated security types supported by the client.
 	 * Set by function SetClientAuthSchemes() */
 	uint32_t *clientAuthSchemes;
 
-	/* When the server is a repeater, this specifies the final destination */
+	/** When the server is a repeater, this specifies the final destination */
 	char *destHost;
 	int destPort;
 
-        /* the QoS IP DSCP for this client */
+        /** the QoS IP DSCP for this client */
         int QoS_DSCP;
 
-        /* hook to handle xvp server messages */
+        /** hook to handle xvp server messages */
 	HandleXvpMsgProc           HandleXvpMsg;
 } rfbClient;
 
@@ -372,10 +377,10 @@ void* rfbClientGetClientData(rfbClient* client, void* tag);
 
 typedef struct _rfbClientProtocolExtension {
 	int* encodings;
-	/* returns TRUE if the encoding was handled */
+	/** returns TRUE if the encoding was handled */
 	rfbBool (*handleEncoding)(rfbClient* cl,
 		rfbFramebufferUpdateRectHeader* rect);
-	/* returns TRUE if it handled the message */
+	/** returns TRUE if it handled the message */
 	rfbBool (*handleMessage)(rfbClient* cl,
 		 rfbServerToClientMsg* message);
 	struct _rfbClientProtocolExtension* next;
@@ -405,12 +410,21 @@ extern int WaitForMessage(rfbClient* client,unsigned int usecs);
 /* vncviewer.c */
 rfbClient* rfbGetClient(int bitsPerSample,int samplesPerPixel,int bytesPerPixel);
 rfbBool rfbInitClient(rfbClient* client,int* argc,char** argv);
-/* rfbClientCleanup() does not touch client->frameBuffer */
+/** rfbClientCleanup() does not touch client->frameBuffer */
 void rfbClientCleanup(rfbClient* client);
 
 #if(defined __cplusplus)
 }
 #endif
 
-#endif
+/**
+ * @}
+ */
 
+/**
+ @page libvncclient_doc LibVNCClient Documentation
+ @section example_code Example Code
+ See SDLvncviewer.c for a rather complete client example.
+*/
+
+#endif