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 <[email protected]>

14 files changed, 371 insertions, 141 deletions

diff --git a/client_examples/SDLvncviewer.c b/client_examples/SDLvncviewer.c
index 5d23ec7..12ef1b0 100644
--- a/client_examples/SDLvncviewer.c
+++ b/client_examples/SDLvncviewer.c
@@ -1,3 +1,7 @@
+/**
+ * @example SDLvncviewer.c
+ */
+
 #include <SDL.h>
 #include <signal.h>
 #include <rfb/rfbclient.h>
diff --git a/client_examples/backchannel.c b/client_examples/backchannel.c
index 643754e..04d154e 100644
--- a/client_examples/backchannel.c
+++ b/client_examples/backchannel.c
@@ -1,4 +1,7 @@
-/* A simple example of an RFB client */
+/**
+ * @example backchannel-client.c
+ * A simple example of an RFB client
+ */
 
 #include <stdio.h>
 #include <stdlib.h>
diff --git a/client_examples/ppmtest.c b/client_examples/ppmtest.c
index 0422937..b8602f0 100644
--- a/client_examples/ppmtest.c
+++ b/client_examples/ppmtest.c
@@ -1,4 +1,7 @@
-/* A simple example of an RFB client */
+/**
+ * @example ppmtest.c
+ * A simple example of an RFB client
+ */
 
 #include <stdio.h>
 #include <stdlib.h>
diff --git a/client_examples/vnc2mpg.c b/client_examples/vnc2mpg.c
index 57fe1a8..10c3d3e 100644
--- a/client_examples/vnc2mpg.c
+++ b/client_examples/vnc2mpg.c
@@ -1,4 +1,5 @@
-/*
+/**
+ * @example vnc2mpg.c
  * Simple movie writer for vnc; based on Libavformat API example from FFMPEG
  * 
  * Copyright (c) 2003 Fabrice Bellard, 2004 Johannes E. Schindelin
diff --git a/examples/backchannel.c b/examples/backchannel.c
index 6a21390..7aa0fa1 100644
--- a/examples/backchannel.c
+++ b/examples/backchannel.c
@@ -1,6 +1,7 @@
 #include <rfb/rfb.h>
 
-/*
+/**
+ * @example backchannel.c
  * This is a simple example demonstrating a protocol extension.
  *
  * The "back channel" permits sending commands between client and server.
diff --git a/examples/camera.c b/examples/camera.c
index 23cb91a..7077790 100644
--- a/examples/camera.c
+++ b/examples/camera.c
@@ -1,5 +1,6 @@
 
-/*
+/**
+ * @example camera.c
  * Question: I need to display a live camera image via VNC. Until now I just 
  * grab an image, set the rect to modified and do a 0.1 s sleep to give the 
  * system time to transfer the data.
diff --git a/examples/example.c b/examples/example.c
index 871ab0c..31bc38d 100644
--- a/examples/example.c
+++ b/examples/example.c
@@ -1,5 +1,5 @@
-/*
- * 
+/**
+ * @example example.c
  * This is an example of how to use libvncserver.
  * 
  * libvncserver example
diff --git a/examples/filetransfer.c b/examples/filetransfer.c
index dacf73d..ff4af11 100644
--- a/examples/filetransfer.c
+++ b/examples/filetransfer.c
@@ -1,3 +1,7 @@
+/**
+ * @example filetransfer.c
+ */
+
 #include <rfb/rfb.h>
 
 int main(int argc,char** argv)
diff --git a/examples/pnmshow.c b/examples/pnmshow.c
index 6268577..734155f 100644
--- a/examples/pnmshow.c
+++ b/examples/pnmshow.c
@@ -1,3 +1,6 @@
+/**
+* @example pnmshow.c
+*/
 #include <stdio.h>
 #include <rfb/rfb.h>
 #include <rfb/keysym.h>
diff --git a/examples/pnmshow24.c b/examples/pnmshow24.c
index 2dec1c1..a8d6c1d 100644
--- a/examples/pnmshow24.c
+++ b/examples/pnmshow24.c
@@ -1,3 +1,7 @@
+/**
+ * @example pnmshow24.c
+ */
+
 #include <stdio.h>
 #include <rfb/rfb.h>
 #include <rfb/keysym.h>
diff --git a/examples/vncev.c b/examples/vncev.c
index affac00..9ebafc9 100644
--- a/examples/vncev.c
+++ b/examples/vncev.c
@@ -1,4 +1,7 @@
-/* This program is a simple server to show events coming from the client */
+/**
+ * @example vncev.c
+ * This program is a simple server to show events coming from the client
+*/
 #ifdef __STRICT_ANSI__
 #define _BSD_SOURCE
 #endif
diff --git a/rfb/rfb.h b/rfb/rfb.h
index 1ea9571..fa530b3 100644
--- a/rfb/rfb.h
+++ b/rfb/rfb.h
@@ -1,8 +1,12 @@
 #ifndef RFB_H
 #define RFB_H
+/**
+ * @defgroup libvncserver_api LibVNCServer API Reference
+ * @{
+ */
 
-/*
- * rfb.h - header file for RFB DDX implementation.
+/**
+ * @file rfb.h
  */
 
 /*
@@ -137,35 +141,38 @@ typedef rfbBool (*rfbPasswordCheckProcPtr)(struct _rfbClientRec* cl,const char*
 typedef enum rfbNewClientAction (*rfbNewClientHookPtr)(struct _rfbClientRec* cl);
 typedef void (*rfbDisplayHookPtr)(struct _rfbClientRec* cl);
 typedef void (*rfbDisplayFinishedHookPtr)(struct _rfbClientRec* cl, int result);
-/* support the capability to view the caps/num/scroll states of the X server */
+/** support the capability to view the caps/num/scroll states of the X server */
 typedef int  (*rfbGetKeyboardLedStateHookPtr)(struct _rfbScreenInfo* screen);
 typedef rfbBool (*rfbXvpHookPtr)(struct _rfbClientRec* cl, uint8_t, uint8_t);
-/* If x==1 and y==1 then set the whole display
+/**
+ * If x==1 and y==1 then set the whole display
  * else find the window underneath x and y and set the framebuffer to the dimensions
  * of that window
  */
 typedef void (*rfbSetSingleWindowProcPtr) (struct _rfbClientRec* cl, int x, int y);
-/* Status determines if the X11 server permits input from the local user 
+/**
+ * Status determines if the X11 server permits input from the local user
  * status==0 or 1
  */
 typedef void (*rfbSetServerInputProcPtr) (struct _rfbClientRec* cl, int status);
-/* Permit the server to allow or deny filetransfers.   This is defaulted to deny
+/**
+ * Permit the server to allow or deny filetransfers.   This is defaulted to deny
  * It is called when a client initiates a connection to determine if it is permitted.
  */
 typedef int  (*rfbFileTransferPermitted) (struct _rfbClientRec* cl);
-/* Handle the textchat messages */
+/** Handle the textchat messages */
 typedef void (*rfbSetTextChat) (struct _rfbClientRec* cl, int length, char *string);
 
 typedef struct {
   uint32_t count;
-  rfbBool is16; /* is the data format short? */
+  rfbBool is16; /**< is the data format short? */
   union {
     uint8_t* bytes;
     uint16_t* shorts;
-  } data; /* there have to be count*3 entries */
+  } data; /**< there have to be count*3 entries */
 } rfbColourMap;
 
-/*
+/**
  * Security handling (RFB protocol version 3.7)
  */
 
@@ -175,31 +182,31 @@ typedef struct _rfbSecurity {
 	struct _rfbSecurity* next;
 } rfbSecurityHandler;
 
-/*
+/**
  * Protocol extension handling.
  */
 
 typedef struct _rfbProtocolExtension {
-	/* returns FALSE if extension should be deactivated for client.
+	/** returns FALSE if extension should be deactivated for client.
 	   if newClient == NULL, it is always deactivated. */
 	rfbBool (*newClient)(struct _rfbClientRec* client, void** data);
-	/* returns FALSE if extension should be deactivated for client.
+	/** returns FALSE if extension should be deactivated for client.
 	   if init == NULL, it stays activated. */
 	rfbBool (*init)(struct _rfbClientRec* client, void* data);
-	/* if pseudoEncodings is not NULL, it contains a 0 terminated
+	/** if pseudoEncodings is not NULL, it contains a 0 terminated
 	   list of the pseudo encodings handled by this extension. */
 	int *pseudoEncodings;
-	/* returns TRUE if that pseudo encoding is handled by the extension.
+	/** returns TRUE if that pseudo encoding is handled by the extension.
 	   encodingNumber==0 means "reset encodings". */
 	rfbBool (*enablePseudoEncoding)(struct _rfbClientRec* client,
 			void** data, int encodingNumber);
-	/* returns TRUE if message was handled */
+	/** returns TRUE if message was handled */
 	rfbBool (*handleMessage)(struct _rfbClientRec* client,
 				void* data,
 				const rfbClientToServerMsg* message);
 	void (*close)(struct _rfbClientRec* client, void* data);
 	void (*usage)(void);
-	/* processArguments returns the number of handled arguments */
+	/** processArguments returns the number of handled arguments */
 	int (*processArgument)(int argc, char *argv[]);
 	struct _rfbProtocolExtension* next;
 } rfbProtocolExtension;
@@ -210,7 +217,7 @@ typedef struct _rfbExtensionData {
 	struct _rfbExtensionData* next;
 } rfbExtensionData;
 
-/*
+/**
  * Per-screen (framebuffer) structure.  There can be as many as you wish,
  * each serving different clients. However, you have to call
  * rfbProcessEvents for each of these.
@@ -218,7 +225,7 @@ typedef struct _rfbExtensionData {
 
 typedef struct _rfbScreenInfo
 {
-    /* this structure has children that are scaled versions of this screen */
+    /** this structure has children that are scaled versions of this screen */
     struct _rfbScreenInfo *scaledScreenNext;
     int scaledScreenRefCount;
 
@@ -232,16 +239,17 @@ typedef struct _rfbScreenInfo
     rfbPixel blackPixel;
     rfbPixel whitePixel;
 
-    /* some screen specific data can be put into a struct where screenData
+    /**
+     * some screen specific data can be put into a struct where screenData
      * points to. You need this if you have more than one screen at the
      * same time while using the same functions.
      */
     void* screenData;
-  
+
     /* additions by libvncserver */
 
     rfbPixelFormat serverFormat;
-    rfbColourMap colourMap; /* set this if rfbServerFormat.trueColour==FALSE */
+    rfbColourMap colourMap; /**< set this if rfbServerFormat.trueColour==FALSE */
     const char* desktopName;
     char thisHost[255];
 
@@ -278,13 +286,13 @@ typedef struct _rfbScreenInfo
 
     rfbPasswordCheckProcPtr passwordCheck;
     void* authPasswdData;
-    /* If rfbAuthPasswdData is given a list, this is the first
-       view only password. */
+    /** If rfbAuthPasswdData is given a list, this is the first
+        view only password. */
     int authPasswdFirstViewOnly;
 
-    /* send only this many rectangles in one update */
+    /** send only this many rectangles in one update */
     int maxRectsPerUpdate;
-    /* this is the amount of milliseconds to wait at least before sending
+    /** this is the amount of milliseconds to wait at least before sending
      * an update. */
     int deferUpdateTime;
 #ifdef TODELETE
@@ -294,7 +302,7 @@ typedef struct _rfbScreenInfo
     rfbBool neverShared;
     rfbBool dontDisconnect;
     struct _rfbClientRec* clientHead;
-    struct _rfbClientRec* pointerClient;  /* "Mutex" for pointer events */
+    struct _rfbClientRec* pointerClient;  /**< "Mutex" for pointer events */
 
 
     /* cursor */
@@ -303,8 +311,9 @@ typedef struct _rfbScreenInfo
     rfbBool dontConvertRichCursorToXCursor;
     struct rfbCursor* cursor;
 
-    /* the frameBufferhas to be supplied by the serving process.
-     * The buffer will not be freed by 
+    /**
+     * the frameBuffer has to be supplied by the serving process.
+     * The buffer will not be freed by
      */
     char* frameBuffer;
     rfbKbdAddEventProcPtr kbdAddEvent;
@@ -317,13 +326,13 @@ typedef struct _rfbScreenInfo
     rfbSetServerInputProcPtr  setServerInput;
     rfbFileTransferPermitted  getFileTransferPermission;
     rfbSetTextChat            setTextChat;
-    
-    /* newClientHook is called just after a new client is created */
+
+    /** newClientHook is called just after a new client is created */
     rfbNewClientHookPtr newClientHook;
-    /* displayHook is called just before a frame buffer update */
+    /** displayHook is called just before a frame buffer update */
     rfbDisplayHookPtr displayHook;
 
-    /* These hooks are called to pass keyboard state back to the client */
+    /** These hooks are called to pass keyboard state back to the client */
     rfbGetKeyboardLedStateHookPtr getKeyboardLedStateHook;
 
 #ifdef LIBVNCSERVER_HAVE_LIBPTHREAD
@@ -331,10 +340,10 @@ typedef struct _rfbScreenInfo
     rfbBool backgroundLoop;
 #endif
 
-    /* if TRUE, an ignoring signal handler is installed for SIGPIPE */
+    /** if TRUE, an ignoring signal handler is installed for SIGPIPE */
     rfbBool ignoreSIGPIPE;
 
-    /* if not zero, only a slice of this height is processed every time
+    /** if not zero, only a slice of this height is processed every time
      * an update should be sent. This should make working on a slow
      * link more interactive. */
     int progressiveSliceHeight;
@@ -342,27 +351,27 @@ typedef struct _rfbScreenInfo
     in_addr_t listenInterface;
     int deferPtrUpdateTime;
 
-    /* handle as many input events as possible (default off) */
+    /** handle as many input events as possible (default off) */
     rfbBool handleEventsEagerly;
 
-    /* rfbEncodingServerIdentity */
+    /** rfbEncodingServerIdentity */
     char *versionString;
 
-    /* What does the server tell the new clients which version it supports */
+    /** What does the server tell the new clients which version it supports */
     int protocolMajorVersion;
     int protocolMinorVersion;
 
-    /* command line authorization of file transfers */
+    /** command line authorization of file transfers */
     rfbBool permitFileTransfer;
 
-    /* displayFinishedHook is called just after a frame buffer update */
+    /** displayFinishedHook is called just after a frame buffer update */
     rfbDisplayFinishedHookPtr displayFinishedHook;
-    /* xvpHook is called to handle an xvp client message */
+    /** xvpHook is called to handle an xvp client message */
     rfbXvpHookPtr xvpHook;
 } rfbScreenInfo, *rfbScreenInfoPtr;
 
 
-/*
+/**
  * rfbTranslateFnType is the type of translation functions.
  */
 
@@ -406,17 +415,17 @@ typedef struct _rfbStatList {
 } rfbStatList;
 
 typedef struct _rfbClientRec {
-  
-    /* back pointer to the screen */
+
+    /** back pointer to the screen */
     rfbScreenInfoPtr screen;
 
-     /* points to a scaled version of the screen buffer in cl->scaledScreenList */
+     /** points to a scaled version of the screen buffer in cl->scaledScreenList */
      rfbScreenInfoPtr scaledScreen;
-     /* how did the client tell us it wanted the screen changed?  Ultra style or palm style? */
+     /** how did the client tell us it wanted the screen changed?  Ultra style or palm style? */
      rfbBool PalmVNC;
-    
-  
-    /* private data. You should put any application client specific data
+
+
+    /** private data. You should put any application client specific data
      * into a struct and let clientData point to it. Don't forget to
      * free the struct via clientGoneHook!
      *
@@ -435,13 +444,13 @@ typedef struct _rfbClientRec {
 #ifdef LIBVNCSERVER_HAVE_LIBPTHREAD
     pthread_t client_thread;
 #endif
-                                /* Possible client states: */
+                                /** Possible client states: */
     enum {
-        RFB_PROTOCOL_VERSION,   /* establishing protocol version */
-	RFB_SECURITY_TYPE,      /* negotiating security (RFB v.3.7) */
-        RFB_AUTHENTICATION,     /* authenticating */
-        RFB_INITIALISATION,     /* sending initialisation messages */
-        RFB_NORMAL              /* normal protocol messages */
+        RFB_PROTOCOL_VERSION,   /**< establishing protocol version */
+	RFB_SECURITY_TYPE,      /**< negotiating security (RFB v.3.7) */
+        RFB_AUTHENTICATION,     /**< authenticating */
+        RFB_INITIALISATION,     /**< sending initialisation messages */
+        RFB_NORMAL              /**< normal protocol messages */
     } state;
 
     rfbBool reverseConnection;
@@ -479,19 +488,19 @@ typedef struct _rfbClientRec {
        the destination copyRegion.  Just before an update is sent we remove
        from the copyRegion anything in the modifiedRegion. */
 
-    sraRegionPtr copyRegion;	/* the destination region of the copy */
-    int copyDX, copyDY;		/* the translation by which the copy happens */
+    sraRegionPtr copyRegion;	/**< the destination region of the copy */
+    int copyDX, copyDY;		/**< the translation by which the copy happens */
 
     sraRegionPtr modifiedRegion;
 
-    /* As part of the FramebufferUpdateRequest, a client can express interest
+    /** As part of the FramebufferUpdateRequest, a client can express interest
        in a subrectangle of the whole framebuffer.  This is stored in the
        requestedRegion member.  In the normal case this is the whole
        framebuffer if the client is ready, empty if it's not. */
 
     sraRegionPtr requestedRegion;
 
-    /* The following member represents the state of the "deferred update" timer
+    /** The following member represents the state of the "deferred update" timer
        - when the framebuffer is modified and the client is ready, in most
        cases it is more efficient to defer sending the update by a few
        milliseconds so that several changes to the framebuffer can be combined
@@ -503,14 +512,14 @@ typedef struct _rfbClientRec {
       int lastPtrY;
       int lastPtrButtons;
 
-    /* translateFn points to the translation function which is used to copy
+    /** translateFn points to the translation function which is used to copy
        and translate a rectangle from the framebuffer to an output buffer. */
 
     rfbTranslateFnType translateFn;
     char *translateLookupTable;
     rfbPixelFormat format;
 
-    /*
+    /**
      * UPDATE_BUF_SIZE must be big enough to send at least one whole line of the
      * framebuffer.  So for a max screen width of say 2K with 32-bit pixels this
      * means 8K minimum.
@@ -526,14 +535,14 @@ typedef struct _rfbClientRec {
     struct _rfbStatList *statMsgList;
     int rawBytesEquivalent;
     int bytesSent;
-        
+
 #ifdef LIBVNCSERVER_HAVE_LIBZ
     /* zlib encoding -- necessary compression state info per client */
 
     struct z_stream_s compStream;
     rfbBool compStreamInited;
     uint32_t zlibCompressLevel;
-    /* the quality level is also used by ZYWRLE */
+    /** the quality level is also used by ZYWRLE */
     int tightQualityLevel;
 
 #ifdef LIBVNCSERVER_HAVE_LIBJPEG
@@ -551,28 +560,28 @@ typedef struct _rfbClientRec {
 
     rfbFileTransferData fileTransfer;
 
-    int     lastKeyboardLedState;     /* keep track of last value so we can send *change* events */
-    rfbBool enableSupportedMessages;  /* client supports SupportedMessages encoding */
-    rfbBool enableSupportedEncodings; /* client supports SupportedEncodings encoding */
-    rfbBool enableServerIdentity;     /* client supports ServerIdentity encoding */
-    rfbBool enableKeyboardLedState;   /* client supports KeyboardState encoding */
-    rfbBool enableLastRectEncoding;   /* client supports LastRect encoding */
-    rfbBool enableCursorShapeUpdates; /* client supports cursor shape updates */
-    rfbBool enableCursorPosUpdates;   /* client supports cursor position updates */
-    rfbBool useRichCursorEncoding;    /* rfbEncodingRichCursor is preferred */
-    rfbBool cursorWasChanged;         /* cursor shape update should be sent */
-    rfbBool cursorWasMoved;           /* cursor position update should be sent */
-    int cursorX,cursorY;	      /* the coordinates of the cursor,
+    int     lastKeyboardLedState;     /**< keep track of last value so we can send *change* events */
+    rfbBool enableSupportedMessages;  /**< client supports SupportedMessages encoding */
+    rfbBool enableSupportedEncodings; /**< client supports SupportedEncodings encoding */
+    rfbBool enableServerIdentity;     /**< client supports ServerIdentity encoding */
+    rfbBool enableKeyboardLedState;   /**< client supports KeyboardState encoding */
+    rfbBool enableLastRectEncoding;   /**< client supports LastRect encoding */
+    rfbBool enableCursorShapeUpdates; /**< client supports cursor shape updates */
+    rfbBool enableCursorPosUpdates;   /**< client supports cursor position updates */
+    rfbBool useRichCursorEncoding;    /**< rfbEncodingRichCursor is preferred */
+    rfbBool cursorWasChanged;         /**< cursor shape update should be sent */
+    rfbBool cursorWasMoved;           /**< cursor position update should be sent */
+    int cursorX,cursorY;	      /**< the coordinates of the cursor,
 					 if enableCursorShapeUpdates = FALSE */
 
-    rfbBool useNewFBSize;             /* client supports NewFBSize encoding */
-    rfbBool newFBSizePending;         /* framebuffer size was changed */
+    rfbBool useNewFBSize;             /**< client supports NewFBSize encoding */
+    rfbBool newFBSizePending;         /**< framebuffer size was changed */
 
     struct _rfbClientRec *prev;
     struct _rfbClientRec *next;
 
 #ifdef LIBVNCSERVER_HAVE_LIBPTHREAD
-    /* whenever a client is referenced, the refCount has to be incremented
+    /** whenever a client is referenced, the refCount has to be incremented
        and afterwards decremented, so that the client is not cleaned up
        while being referenced.
        Use the functions rfbIncrClientRef(cl) and rfbDecrClientRef(cl);
@@ -592,17 +601,17 @@ typedef struct _rfbClientRec {
     int zywrleBuf[rfbZRLETileWidth * rfbZRLETileHeight];
 #endif
 
-    /* if progressive updating is on, this variable holds the current
+    /** if progressive updating is on, this variable holds the current
      * y coordinate of the progressive slice. */
     int progressiveSliceY;
 
     rfbExtensionData* extensions;
 
-    /* for threaded zrle */
+    /** for threaded zrle */
     char *zrleBeforeBuf;
     void *paletteHelper;
 
-    /* for thread safety for rfbSendFBUpdate() */
+    /** for thread safety for rfbSendFBUpdate() */
 #ifdef LIBVNCSERVER_HAVE_LIBPTHREAD
 #define LIBVNCSERVER_SEND_MUTEX
     MUTEX(sendMutex);
@@ -610,7 +619,7 @@ typedef struct _rfbClientRec {
 
 } rfbClientRec, *rfbClientPtr;
 
-/*
+/**
  * This macro is used to test whether there is a framebuffer update needing to
  * be sent to the client.
  */
@@ -769,7 +778,7 @@ extern rfbBool rfbSendRectEncodingUltra(rfbClientPtr cl, int x,int y,int w,int h
 #ifdef LIBVNCSERVER_HAVE_LIBZ
 /* zlib.c */
 
-/* Minimum zlib rectangle size in bytes.  Anything smaller will
+/** Minimum zlib rectangle size in bytes.  Anything smaller will
  * not compress well due to overhead.
  */
 #define VNC_ENCODE_ZLIB_MIN_COMP_SIZE (17)
@@ -801,16 +810,16 @@ extern rfbBool rfbSendRectEncodingTight(rfbClientPtr cl, int x,int y,int w,int h
 /* cursor.c */
 
 typedef struct rfbCursor {
-    /* set this to true if LibVNCServer has to free this cursor */
+    /** set this to true if LibVNCServer has to free this cursor */
     rfbBool cleanup, cleanupSource, cleanupMask, cleanupRichSource;
-    unsigned char *source;			/* points to bits */
-    unsigned char *mask;			/* points to bits */
-    unsigned short width, height, xhot, yhot;	/* metrics */
-    unsigned short foreRed, foreGreen, foreBlue; /* device-independent colour */
-    unsigned short backRed, backGreen, backBlue; /* device-independent colour */
-    unsigned char *richSource; /* source bytes for a rich cursor */
-    unsigned char *alphaSource; /* source for alpha blending info */
-    rfbBool alphaPreMultiplied; /* if richSource already has alpha applied */
+    unsigned char *source;			/**< points to bits */
+    unsigned char *mask;			/**< points to bits */
+    unsigned short width, height, xhot, yhot;	/**< metrics */
+    unsigned short foreRed, foreGreen, foreBlue; /**< device-independent colour */
+    unsigned short backRed, backGreen, backBlue; /**< device-independent colour */
+    unsigned char *richSource; /**< source bytes for a rich cursor */
+    unsigned char *alphaSource; /**< source for alpha blending info */
+    rfbBool alphaPreMultiplied; /**< if richSource already has alpha applied */
 } rfbCursor, *rfbCursorPtr;
 extern unsigned char rfbReverseByte[0x100];
 
@@ -825,7 +834,7 @@ extern void rfbMakeRichCursorFromXCursor(rfbScreenInfoPtr rfbScreen,rfbCursorPtr
 extern void rfbFreeCursor(rfbCursorPtr cursor);
 extern void rfbSetCursor(rfbScreenInfoPtr rfbScreen,rfbCursorPtr c);
 
-/* cursor handling for the pointer */
+/** cursor handling for the pointer */
 extern void rfbDefaultPtrAddEvent(int buttonMask,int x,int y,rfbClientPtr cl);
 
 /* zrle.c */
@@ -842,7 +851,7 @@ extern void rfbPrintStats(rfbClientPtr cl);
 
 typedef struct rfbFontData {
   unsigned char* data;
-  /*
+  /**
     metaData is a 256*5 array:
     for each character
     (offset,width,height,x,y)
@@ -852,18 +861,18 @@ typedef struct rfbFontData {
 
 int rfbDrawChar(rfbScreenInfoPtr rfbScreen,rfbFontDataPtr font,int x,int y,unsigned char c,rfbPixel colour);
 void rfbDrawString(rfbScreenInfoPtr rfbScreen,rfbFontDataPtr font,int x,int y,const char* string,rfbPixel colour);
-/* if colour==backColour, background is transparent */
+/** if colour==backColour, background is transparent */
 int rfbDrawCharWithClip(rfbScreenInfoPtr rfbScreen,rfbFontDataPtr font,int x,int y,unsigned char c,int x1,int y1,int x2,int y2,rfbPixel colour,rfbPixel backColour);
 void rfbDrawStringWithClip(rfbScreenInfoPtr rfbScreen,rfbFontDataPtr font,int x,int y,const char* string,int x1,int y1,int x2,int y2,rfbPixel colour,rfbPixel backColour);
 int rfbWidthOfString(rfbFontDataPtr font,const char* string);
 int rfbWidthOfChar(rfbFontDataPtr font,unsigned char c);
 void rfbFontBBox(rfbFontDataPtr font,unsigned char c,int* x1,int* y1,int* x2,int* y2);
-/* this returns the smallest box enclosing any character of font. */
+/** this returns the smallest box enclosing any character of font. */
 void rfbWholeFontBBox(rfbFontDataPtr font,int *x1, int *y1, int *x2, int *y2);
 
-/* dynamically load a linux console font (4096 bytes, 256 glyphs a 8x16 */
+/** dynamically load a linux console font (4096 bytes, 256 glyphs a 8x16 */
 rfbFontDataPtr rfbLoadConsoleFont(char *filename);
-/* free a dynamically loaded font */
+/** free a dynamically loaded font */
 void rfbFreeFont(rfbFontDataPtr font);
 
 /* draw.c */
@@ -874,7 +883,7 @@ void rfbDrawLine(rfbScreenInfoPtr s,int x1,int y1,int x2,int y2,rfbPixel col);
 
 /* selbox.c */
 
-/* this opens a modal select box. list is an array of strings, the end marked
+/** this opens a modal select box. list is an array of strings, the end marked
    with a NULL.
    It returns the index in the list or -1 if cancelled or something else
    wasn't kosher. */
@@ -918,7 +927,7 @@ rfbBool rfbEnableExtension(rfbClientPtr cl, rfbProtocolExtension* extension,
 rfbBool rfbDisableExtension(rfbClientPtr cl, rfbProtocolExtension* extension);
 void* rfbGetExtensionClientData(rfbClientPtr cl, rfbProtocolExtension* extension);
 
-/* to check against plain passwords */
+/** to check against plain passwords */
 rfbBool rfbCheckPasswordByList(rfbClientPtr cl,const char* response,int len);
 
 /* functions to make a vnc server */
@@ -952,7 +961,7 @@ extern rfbBool rfbIsActive(rfbScreenInfoPtr screenInfo);
 
 /* TightVNC file transfer extension */
 void rfbRegisterTightVNCFileTransferExtension();
-void rfbUnregisterTightVNCFileTransferExtension(); 
+void rfbUnregisterTightVNCFileTransferExtension();
 
 /* Statistics */
 extern char *messageNameServer2Client(uint32_t type, char *buf, int len);
@@ -980,10 +989,10 @@ extern int rfbStatGetMessageCountRcvd(rfbClientPtr cl, uint32_t type);
 extern int rfbStatGetEncodingCountSent(rfbClientPtr cl, uint32_t type);
 extern int rfbStatGetEncodingCountRcvd(rfbClientPtr cl, uint32_t type);
 
-/* Set which version you want to advertise 3.3, 3.6, 3.7 and 3.8 are currently supported*/
+/** Set which version you want to advertise 3.3, 3.6, 3.7 and 3.8 are currently supported*/
 extern void rfbSetProtocolVersion(rfbScreenInfoPtr rfbScreen, int major_, int minor_);
 
-/* send a TextChat message to a client */
+/** send a TextChat message to a client */
 extern rfbBool rfbSendTextChatMessage(rfbClientPtr cl, uint32_t length, char *buffer);
 
 
@@ -993,5 +1002,174 @@ extern rfbBool rfbSendTextChatMessage(rfbClientPtr cl, uint32_t length, char *bu
 }
 #endif
 
-#endif
+/**
+ * @}
+ */
+
 
+/**
+ @page libvncserver_doc LibVNCServer Documentation
+ @section create_server Creating a server instance
+ To make a server, you just have to initialise a server structure using the
+ function rfbGetScreen(), like
+ @code
+   rfbScreenInfoPtr screen =
+     rfbGetScreen(argc,argv,screenwidth,screenheight,8,3,bpp);
+ @endcode
+ where byte per pixel should be 1, 2 or 4. If performance doesn't matter,
+ you may try bpp=3 (internally one cannot use native data types in this
+ case; if you want to use this, look at pnmshow24.c).
+
+ You then can set hooks and io functions (see @ref making_it_interactive) or other
+ options (see @ref server_options).
+
+ And you allocate the frame buffer like this:
+ @code
+     screen->frameBuffer = (char*)malloc(screenwidth*screenheight*bpp);
+ @endcode
+ After that, you initialize the server, like
+ @code
+   rfbInitServer(screen);
+ @endcode
+ You can use a blocking event loop, a background (pthread based) event loop,
+ or implement your own using the rfbProcessEvents() function.
+
+ @subsection server_options Optional Server Features
+
+ These options have to be set between rfbGetScreen() and rfbInitServer().
+
+ If you already have a socket to talk to, just set rfbScreenInfo::inetdSock
+ (originally this is for inetd handling, but why not use it for your purpose?).
+
+ To also start an HTTP server (running on port 5800+display_number), you have
+ to set rfbScreenInfo::httpDir to a directory containing vncviewer.jar and
+ index.vnc (like the included "classes" directory).
+
+ @section making_it_interactive Making it interactive
+
+ Whenever you draw something, you have to call
+ @code
+  rfbMarkRectAsModified(screen,x1,y1,x2,y2).
+ @endcode
+ This tells LibVNCServer to send updates to all connected clients.
+
+ There exist the following IO functions as members of rfbScreen:
+ rfbScreenInfo::kbdAddEvent(), rfbScreenInfo::kbdReleaseAllKeys(), rfbScreenInfo::ptrAddEvent() and rfbScreenInfo::setXCutText()
+
+ rfbScreenInfo::kbdAddEvent()
+   is called when a key is pressed.
+ rfbScreenInfo::kbdReleaseAllKeys()
+   is not called at all (maybe in the future).
+ rfbScreenInfo::ptrAddEvent()
+   is called when the mouse moves or a button is pressed.
+   WARNING: if you want to have proper cursor handling, call
+	rfbDefaultPtrAddEvent()
+   in your own function. This sets the coordinates of the cursor.
+ rfbScreenInfo::setXCutText()
+   is called when the selection changes.
+
+ There are only two hooks:
+ rfbScreenInfo::newClientHook()
+   is called when a new client has connected.
+ rfbScreenInfo::displayHook()
+   is called just before a frame buffer update is sent.
+
+ You can also override the following methods:
+ rfbScreenInfo::getCursorPtr()
+   This could be used to make an animated cursor (if you really want ...)
+ rfbScreenInfo::setTranslateFunction()
+   If you insist on colour maps or something more obscure, you have to
+   implement this. Default is a trueColour mapping.
+
+ @section cursor_handling Cursor handling
+
+ The screen holds a pointer
+  rfbScreenInfo::cursor
+ to the current cursor. Whenever you set it, remember that any dynamically
+ created cursor (like return value from rfbMakeXCursor()) is not free'd!
+
+ The rfbCursor structure consists mainly of a mask and a source. The rfbCursor::mask
+ describes, which pixels are drawn for the cursor (a cursor needn't be
+ rectangular). The rfbCursor::source describes, which colour those pixels should have.
+
+ The standard is an XCursor: a cursor with a foreground and a background
+ colour (stored in backRed,backGreen,backBlue and the same for foreground
+ in a range from 0-0xffff). Therefore, the arrays "mask" and "source"
+ contain pixels as single bits stored in bytes in MSB order. The rows are
+ padded, such that each row begins with a new byte (i.e. a 10x4
+ cursor's mask has 2x4 bytes, because 2 bytes are needed to hold 10 bits).
+
+ It is however very easy to make a cursor like this:
+ @code
+ char* cur="    "
+           " xx "
+	   " x  "
+	   "    ";
+ char* mask="xxxx"
+            "xxxx"
+            "xxxx"
+            "xxx ";
+ rfbCursorPtr c=rfbMakeXCursor(4,4,cur,mask);
+ @endcode
+ You can even set rfbCursor::mask to NULL in this call and LibVNCServer will calculate
+ a mask for you (dynamically, so you have to free it yourself).
+
+ There is also an array named rfbCursor::richSource for colourful cursors. They have
+ the same format as the frameBuffer (i.e. if the server is 32 bit,
+ a 10x4 cursor has 4x10x4 bytes).
+
+ @section screen_client_difference What is the difference between rfbScreenInfoPtr and rfbClientPtr?
+
+ The rfbScreenInfoPtr is a pointer to a rfbScreenInfo structure, which
+ holds information about the server, like pixel format, io functions,
+ frame buffer etc. The rfbClientPtr is a pointer to an rfbClientRec structure, which holds
+ information about a client, like pixel format, socket of the
+ connection, etc. A server can have several clients, but needn't have any. So, if you
+ have a server and three clients are connected, you have one instance
+ of a rfbScreenInfo and three instances of rfbClientRec's.
+
+ The rfbClientRec structure holds a member rfbClientRec::screen which points to the server.
+ So, to access the server from the client structure, you use client->screen.
+
+ To access all clients from a server be sure to use the provided iterator
+  rfbGetClientIterator()
+ with
+  rfbClientIteratorNext()
+ and
+  rfbReleaseClientIterator()
+ to prevent thread clashes.
+
+ @section example_code Example Code
+
+ There are two documented examples included:
+  - example.c, a shared scribble sheet
+  - pnmshow.c, a program to show PNMs (pictures) over the net.
+
+ The examples are not too well documented, but easy straight forward and a
+ good starting point.
+
+ Try example.c: it outputs on which port it listens (default: 5900), so it is
+ display 0. To view, call @code	vncviewer :0 @endcode
+ You should see a sheet with a gradient and "Hello World!" written on it. Try
+ to paint something. Note that everytime you click, there is some bigger blot,
+ whereas when you drag the mouse while clicked you draw a line. The size of the
+ blot depends on the mouse button you click. Open a second vncviewer with
+ the same parameters and watch it as you paint in the other window. This also
+ works over internet. You just have to know either the name or the IP of your
+ machine. Then it is @code vncviewer machine.where.example.runs.com:0 @endcode
+ or similar for the remote client. Now you are ready to type something. Be sure
+ that your mouse sits still, because everytime the mouse moves, the cursor is
+ reset to the position of the pointer! If you are done with that demo, press
+ the down or up arrows. If your viewer supports it, then the dimensions of the
+ sheet change. Just press Escape in the viewer. Note that the server still
+ runs, even if you closed both windows. When you reconnect now, everything you
+ painted and wrote is still there. You can press "Page Up" for a blank page.
+
+ The demo pnmshow.c is much simpler: you either provide a filename as argument
+ or pipe a file through stdin. Note that the file has to be a raw pnm/ppm file,
+ i.e. a truecolour graphics. Only the Escape key is implemented. This may be
+ the best starting point if you want to learn how to use LibVNCServer. You
+ are confronted with the fact that the bytes per pixel can only be 8, 16 or 32.
+*/
+
+#endif
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
diff --git a/rfb/rfbproto.h b/rfb/rfbproto.h
index 6fe14bc..023528b 100644
--- a/rfb/rfbproto.h
+++ b/rfb/rfbproto.h
@@ -1,6 +1,17 @@
 #ifndef RFBPROTO_H
 #define RFBPROTO_H
 
+/**
+ @mainpage
+ @li @ref libvncserver_api
+ @li @ref libvncserver_doc
+
+
+ @li @ref libvncclient_api
+ @li @ref libvncclient_doc
+
+*/
+
 /*
  *  Copyright (C) 2005 Rohit Kumar, Johannes E. Schindelin
  *  Copyright (C) 2000-2002 Constantin Kaplinsky.  All Rights Reserved.