doc

Signed-off-by: Mattias Andrée <maandree@operamail.com>

3 files changed, 331 insertions, 30 deletions

diff --git a/src/lib/fake-w32-gdi.c b/src/lib/fake-w32-gdi.c
index f151186..8fb1ab7 100644
--- a/src/lib/fake-w32-gdi.c
+++ b/src/lib/fake-w32-gdi.c
@@ -37,7 +37,14 @@
 /* Use dummy translation. */
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx */
+
+/**
+ * Get the device context for a window or the entire screen.
+ * 
+ * @param   hWnd  The windows, `NULL` for the entire screen.
+ * @return        The device context.
+ * @see           http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx
+ */
 HDC GetDC(HWND hWnd)
 {
   /* Just a non-NULL value. */
@@ -45,7 +52,15 @@ HDC GetDC(HWND hWnd)
   return (HDC*)16;
 }
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx */
+
+/**
+ * Free a device context.
+ * 
+ * @param   hWnd  The window whose device context is `hDC`, `NULL` for the entire screen.
+ * @param   hDC   The device context to free.
+ * @return        Whether the call was successful.
+ * @see           http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx
+ */
 int ReleaseDC(HWND hWnd, HDC hDC)
 {
   /* Always successful. */
@@ -55,7 +70,16 @@ int ReleaseDC(HWND hWnd, HDC hDC)
 }
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx */
+
+/**
+ * Get information (capabilities) for a device context.
+ * 
+ * @param   hDC     The device context.
+ * @param   nIndex  The information to retrieve, may be `COLORMGMTCAPS`.
+ * @return          The details of the queried information, can return `CM_GAMMA_RAMP`
+ *                  if `nIndex` is `COLORMGMTCAPS`.
+ * @see             http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx
+ */
 int GetDeviceCaps(HDC hDC, int nIndex)
 {
   /* We have gamma ramps if the user asks for colour management capabilities. */
@@ -63,7 +87,16 @@ int GetDeviceCaps(HDC hDC, int nIndex)
   return CM_GAMMA_RAMP + nIndex - COLORMGMTCAPS;
 }
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx */
+
+/**
+ * Set the gamma ramps for a device.
+ * 
+ * @param   hDC     The device context.
+ * @param   lpRamp  The gamma ramps joined in the order: red, green, blue.
+ *                  This is a `WORD*` casted to `void*`.
+ * @return          Whether the call was successful.
+ * @see             http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx
+ */
 BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 {
   /* Always successful. */
@@ -72,7 +105,16 @@ BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
   return TRUE;
 }
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx */
+
+/**
+ * Get the current gamma ramps for a device.
+ * 
+ * @param   hDC     The device context.
+ * @param   lpRamp  The output for the gamma ramps joined in the order: red, green, blue.
+ *                  This is a `WORD*` casted to `void*`.
+ * @return          Whether the call was successful.
+ * @see             http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx
+ */
 BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 {
   /* Always successful. */
@@ -82,9 +124,21 @@ BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 }
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx */
+
+/**
+ * Get the context for a device
+ * 
+ * @param   lpszDriver  The driver or a display device, use "DISPLAY" if you want a display.
+ * @param   lpszDevice  The name of the device. If you want a display use can use the member
+ *                      name `DeviceName` in the third parameter, an output parameter, of
+ *                      `EnumDisplayDevices`.
+ * @param   lpszOutput  We will always use `NULL` here.
+ * @param   lpInitData  We will always use `NULL` here. This should actually by a `const DEVMODE*`.
+ * @return  -
+ * @see     http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx
+ */
 HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice,
-	     void* restrict lpszOutput, void* restrict lpInitData)
+	     LPCTSTR restrict lpszOutput, const void* restrict lpInitData)
 {
   /* `NULL` if not asking for a CRTC, otherwise a non-NULL value. */
   (void) lpszOutput;
@@ -94,7 +148,17 @@ HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice,
 }
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx */
+/**
+ * Get a display device by its name or index.
+ * 
+ * @param   lpDevice         The name of the device, use `NULL` to base the call on `iDevNum` instead.
+ * @param   iDevNum          The index of the device.
+ * @param   lpDisplayDevice  Output for the found device.
+ * @param   dwFlags          Flags, we will always use zero.
+ * @return                   Whether the call was successful. Zero is also returned if `iDevNum`
+ *                           is greater than the largest device index on the system.
+ * @see                      http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx
+ */
 BOOL EnumDisplayDevices(LPCTSTR lpDevice, restrict DWORD iDevNum,
 			PDISPLAY_DEVICE restrict lpDisplayDevice, DWORD dwFlags)
 {
@@ -167,7 +231,13 @@ static size_t dc_count = 0;
 
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx */
+/**
+ * Get the device context for a window or the entire screen.
+ * 
+ * @param   hWnd  The windows, `NULL` for the entire screen.
+ * @return        The device context.
+ * @see           http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx
+ */
 HDC GetDC(HWND hWnd)
 {
   /* Return the primary CRTC. */
@@ -176,7 +246,14 @@ HDC GetDC(HWND hWnd)
 }
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx */
+/**
+ * Free a device context.
+ * 
+ * @param   hWnd  The window whose device context is `hDC`, `NULL` for the entire screen.
+ * @param   hDC   The device context to free.
+ * @return        Whether the call was successful.
+ * @see           http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx
+ */
 int ReleaseDC(HWND hWnd, HDC hDC)
 {
   /* Disconnect from the RandR display when all monitors have been closed. */
@@ -195,7 +272,16 @@ int ReleaseDC(HWND hWnd, HDC hDC)
 }
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx */
+
+/**
+ * Get information (capabilities) for a device context.
+ * 
+ * @param   hDC     The device context.
+ * @param   nIndex  The information to retrieve, may be `COLORMGMTCAPS`.
+ * @return          The details of the queried information, can return `CM_GAMMA_RAMP`
+ *                  if `nIndex` is `COLORMGMTCAPS`.
+ * @see             http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx
+ */
 int GetDeviceCaps(HDC hDC, int nIndex)
 {
   /* We have gamma ramps if the user asks for colour management capabilities. */
@@ -204,14 +290,22 @@ int GetDeviceCaps(HDC hDC, int nIndex)
 }
 
 
-/* xcb violates the rule to never return struct:s. */
+/* xcb violates the rule to never return `struct`:s. */
 #ifdef __GCC__
 # pragma GCC diagnostic push
 # pragma GCC diagnostic ignored "-Waggregate-return"
 #endif
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx */
+/**
+ * Set the gamma ramps for a device.
+ * 
+ * @param   hDC     The device context.
+ * @param   lpRamp  The gamma ramps joined in the order: red, green, blue.
+ *                  This is a `WORD*` casted to `void*`.
+ * @return          Whether the call was successful.
+ * @see             http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx
+ */
 BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 {
   /* We assume that our gamma ramps are of the same size
@@ -226,7 +320,15 @@ BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 }
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx */
+/**
+ * Get the current gamma ramps for a device.
+ * 
+ * @param   hDC     The device context.
+ * @param   lpRamp  The output for the gamma ramps joined in the order: red, green, blue.
+ *                  This is a `WORD*` casted to `void*`.
+ * @return          Whether the call was successful.
+ * @see             http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx
+ */
 BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 {
   xcb_randr_get_crtc_gamma_cookie_t gamma_cookie;
@@ -255,9 +357,21 @@ BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp)
 }
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx */
+
+/**
+ * Get the context for a device
+ * 
+ * @param   lpszDriver  The driver or a display device, use "DISPLAY" if you want a display.
+ * @param   lpszDevice  The name of the device. If you want a display use can use the member
+ *                      name `DeviceName` in the third parameter, an output parameter, of
+ *                      `EnumDisplayDevices`.
+ * @param   lpszOutput  We will always use `NULL` here.
+ * @param   lpInitData  We will always use `NULL` here. This should actually by a `const DEVMODE*`.
+ * @return  -
+ * @see     http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx
+ */
 HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice,
-	     void* restrict lpszOutput, void* restrict lpInitData)
+	     LPCTSTR restrict lpszOutput, const void* restrict lpInitData)
 {
   int crtc_index = atoi(lpszDevice);
   
@@ -325,7 +439,17 @@ HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice,
 #endif
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx */
+/**
+ * Get a display device by its name or index.
+ * 
+ * @param   lpDevice         The name of the device, use `NULL` to base the call on `iDevNum` instead.
+ * @param   iDevNum          The index of the device.
+ * @param   lpDisplayDevice  Output for the found device.
+ * @param   dwFlags          Flags, we will always use zero.
+ * @return                   Whether the call was successful. Zero is also returned if `iDevNum`
+ *                           is greater than the largest device index on the system.
+ * @see                      http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx
+ */
 BOOL EnumDisplayDevices(LPCTSTR restrict lpDevice, DWORD iDevNum,
 			PDISPLAY_DEVICE restrict lpDisplayDevice, DWORD dwFlags)
 {
diff --git a/src/lib/fake-w32-gdi.h b/src/lib/fake-w32-gdi.h
index 6c49e6c..c777fa6 100644
--- a/src/lib/fake-w32-gdi.h
+++ b/src/lib/fake-w32-gdi.h
@@ -30,54 +30,230 @@
 #include <stdint.h>
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx */
+/**
+ * One of the Windows `typedef`:s for unsigned 16-bit integer.
+ * This is the one used in these functions.
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#WORD
+ */
 typedef uint16_t WORD;
-typedef uint32_t DWORD;
+
+/**
+ * One of the Windows `typedef`:s for unsigned 32-bit integer.
+ * This is the one used in these functions.
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#DWORD
+ */
+typedef uint32_t DWORD ;
+/* XXX Documented to be 32-bit but defined as `typedef unsigned long DWORD`, which is it? */
+
+/**
+ * One of the Windows `typedef` for booleanic values, the `int` variant.
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#BOOL
+ */
 typedef int BOOL;
+
+/**
+ * Windows `typedef` for a device context (the 'h' stands for 'handle'.)
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#HDC
+ */
 typedef void* HDC;
+
+/**
+ * Windows `typedef` for a window (the 'h' stands for 'handle'.)
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#HWND
+ */
 typedef void* HWND;
+
+/**
+ * One of the Windows `typedef`:s for `void*`, a generic pointer.
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#LPVOID
+ */
 typedef void* LPVOID;
+
+/**
+ * A silly Windows `typedef` for a `const char*`, a constant string.
+ * It is also defined as NUL-terminated, but so are all C-strings
+ * and it makes no difference. However if `UNICODE` were to be defined
+ * it would be `const wchar_t*`.
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#LPCTSTR
+ */
 typedef const char* LPCTSTR;
+
+/**
+ * Even more silly. A Windows `typedef` for either `wchar_t` or
+ * `char`, depending on whether `UNICODE` is defined. We will
+ * assume `UNICODE` is not definied because that is just silly.
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#TCHAR
+ */
 typedef char TCHAR;
+
+/**
+ * Apperently we need `TRUE` to be defined to understand code,
+ * at least in Windows...
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#BOOL
+ */
 #define TRUE  1
+
+/**
+ * Apperently we need `FALSE` to be defined to understand code,
+ * at least in Windows...
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/aa383751(v=vs.85).aspx#BOOL
+ */
 #define FALSE 0
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx */
+
+/**
+ * Get the device context for a window or the entire screen.
+ * 
+ * @param   hWnd  The window, `NULL` for the entire screen.
+ * @return        The device context.
+ * @see           http://msdn.microsoft.com/en-us/library/windows/desktop/dd144871(v=vs.85).aspx
+ */
 HDC GetDC(HWND hWnd);
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx */
+/**
+ * Free a device context.
+ * 
+ * @param   hWnd  The window whose device context is `hDC`, `NULL` for the entire screen.
+ * @param   hDC   The device context to free.
+ * @return        Whether the call was successful.
+ * @see           http://msdn.microsoft.com/en-us/library/windows/desktop/dd162920(v=vs.85).aspx
+ */
 int ReleaseDC(HWND hWnd, HDC hDC);
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx */
+/**
+ * Get information (capabilities) for a device context.
+ * 
+ * @param   hDC     The device context.
+ * @param   nIndex  The information to retrieve, may be `COLORMGMTCAPS`.
+ * @return          The details of the queried information, can return `CM_GAMMA_RAMP`
+ *                  if `nIndex` is `COLORMGMTCAPS`.
+ * @see             http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx
+ */
 int GetDeviceCaps(HDC hDC, int nIndex) __attribute__((const));
+
+/**
+ * Colour management capabilities
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx
+ */
 #define COLORMGMTCAPS 1
+
+/**
+ * Colour management capabilities: has gamma ramps
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/dd144877(v=vs.85).aspx
+ */
 #define CM_GAMMA_RAMP 1
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx */
+
+/**
+ * Set the gamma ramps for a device.
+ * 
+ * @param   hDC     The device context.
+ * @param   lpRamp  The gamma ramps joined in the order: red, green, blue.
+ *                  This is a `WORD*` casted to `void*`.
+ * @return          Whether the call was successful.
+ * @see             http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx
+ */
 BOOL SetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp);
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx */
+/**
+ * Get the current gamma ramps for a device.
+ * 
+ * @param   hDC     The device context.
+ * @param   lpRamp  The output for the gamma ramps joined in the order: red, green, blue.
+ *                  This is a `WORD*` casted to `void*`.
+ * @return          Whether the call was successful.
+ * @see             http://msdn.microsoft.com/en-us/library/windows/desktop/dd316946(v=vs.85).aspx
+ */
 BOOL GetDeviceGammaRamp(HDC hDC, LPVOID restrict lpRamp);
 
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx */
+/**
+ * Get the context for a device
+ * 
+ * @param   lpszDriver  The driver or a display device, use "DISPLAY" if you want a display.
+ * @param   lpszDevice  The name of the device. If you want a display use can use the member
+ *                      name `DeviceName` in the third parameter, an output parameter, of
+ *                      `EnumDisplayDevices`.
+ * @param   lpszOutput  We will always use `NULL` here.
+ * @param   lpInitData  We will always use `NULL` here. This should actually by a `const DEVMODE*`.
+ * @return              The context for the device.
+ * @see                 http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx
+ */
 HDC CreateDC(LPCTSTR restrict lpszDriver, LPCTSTR restrict lpszDevice,
-	     void* restrict lpszOutput, void* restrict lpInitData);
+	     LPCTSTR restrict lpszOutput, const void* restrict lpInitData);
+
+/**
+ * This macro does not seem to have an official documentation that is correct.
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/dd183490(v=vs.85).aspx
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/dd374074(v=vs.85).aspx
+ */
 #define TEXT(X) ((LPCTSTR)(X))
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd183569(v=vs.85).aspx */
+
+/**
+ * Information about a display device.
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/dd183569(v=vs.85).aspx
+ */
 typedef struct
 {
+  /**
+   * Set this to `sizeof(DISPLAY_DEVICE)`.
+   */
   DWORD cb;
+  
+  /**
+   * The name of the device.
+   */
   TCHAR DeviceName[32];
+  
+  /**
+   * The status of the device, can include `DISPLAY_DEVICE_ACTIVE`.
+   */
   DWORD StateFlags;
+  
 } DISPLAY_DEVICE;
+
+/**
+ * Appearently we are incapable of putting asterisks at the
+ * end of types names, so istead we preprend them with 'P'.
+ * 
+ * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd183569(v=vs.85).aspx
+ */
 typedef DISPLAY_DEVICE* PDISPLAY_DEVICE;
+
+/**
+ * The monitor is "on".
+ * 
+ * @see http://msdn.microsoft.com/en-us/library/windows/desktop/dd183569(v=vs.85).aspx
+ */
 #define DISPLAY_DEVICE_ACTIVE 1
 
-/* http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx */
+/**
+ * Get a display device by its name or index.
+ * 
+ * @param   lpDevice         The name of the device, use `NULL` to base the call on `iDevNum` instead.
+ * @param   iDevNum          The index of the device.
+ * @param   lpDisplayDevice  Output for the found device.
+ * @param   dwFlags          Flags, we will always use zero.
+ * @return                   Whether the call was successful. Zero is also returned if `iDevNum`
+ *                           is greater than the largest device index on the system.
+ * @see                      http://msdn.microsoft.com/en-us/library/windows/desktop/dd162609(v=vs.85).aspx
+ */
 BOOL EnumDisplayDevices(LPCTSTR restrict lpDevice, DWORD iDevNum,
 			PDISPLAY_DEVICE restrict lpDisplayDevice, DWORD dwFlags);
 
diff --git a/src/lib/gamma-w32-gdi.c b/src/lib/gamma-w32-gdi.c
index c5dc655..8104b18 100644
--- a/src/lib/gamma-w32-gdi.c
+++ b/src/lib/gamma-w32-gdi.c
@@ -37,8 +37,9 @@
 
 
 /**
- * The gamma ramp size that devices will
- * always have in Windows GDI.
+ * The gamma ramp size that devices will always have in Windows GDI.
+ * 
+ * @see  http://msdn.microsoft.com/en-us/library/windows/desktop/dd372194(v=vs.85).aspx
  */
 #define GAMMA_RAMP_SIZE  256