[os2] Improve documentation

Move the API documentation for the OS/2 backend from the .h file to the .c file and use the correct format.

2 files changed, 139 insertions, 115 deletions

diff --git a/src/cairo-os2-surface.c b/src/cairo-os2-surface.c
index f3824849..e40cdcea 100644
--- a/src/cairo-os2-surface.c
+++ b/src/cairo-os2-surface.c
@@ -86,6 +86,16 @@ DisableFPUException (void)
     _control87 (usCW, MCW_EM | 0x80);
 }
 
+/**
+ * cairo_os2_init:
+ *
+ * Initializes the Cairo library. This function is automatically called if
+ * Cairo was compiled to be a DLL (however it's not a problem if it's called
+ * multiple times). But if you link to Cairo statically, you have to call it
+ * once to set up Cairo's internal structures and mutexes.
+ *
+ * Since: 1.4
+ **/
 cairo_public void
 cairo_os2_init (void)
 {
@@ -102,6 +112,16 @@ cairo_os2_init (void)
     CAIRO_MUTEX_INITIALIZE ();
 }
 
+/**
+ * cairo_os2_fini:
+ *
+ * Uninitializes the Cairo library. This function is automatically called if
+ * Cairo was compiled to be a DLL (however it's not a problem if it's called
+ * multiple times). But if you link to Cairo statically, you have to call it
+ * once to shut down Cairo, to let it free all the resources it has allocated.
+ *
+ * Since: 1.4
+ **/
 cairo_public void
 cairo_os2_fini (void)
 {
@@ -716,6 +736,26 @@ _cairo_os2_surface_get_extents (void                    *abstract_surface,
     return CAIRO_STATUS_SUCCESS;
 }
 
+/**
+ * cairo_os2_surface_create:
+ * @hps_client_window: the presentation handle to bind the surface to
+ * @width: the width of the surface
+ * @height: the height of the surface
+ *
+ * Create a Cairo surface which is bound to a given presentation space (HPS).
+ * The surface will be created to have the given size.
+ * By default every change to the surface will be made visible immediately by
+ * blitting it into the window. This can be changed with
+ * cairo_os2_surface_set_manual_window_refresh().
+ * Note that the surface will contain garbage when created, so the pixels have
+ * to be initialized by hand first. You can use the Cairo functions to fill it
+ * with black, or use cairo_surface_mark_dirty() to fill the surface with pixels
+ * from the window/HPS.
+ *
+ * Return value: the newly created surface
+ *
+ * Since: 1.4
+ **/
 cairo_surface_t *
 cairo_os2_surface_create (HPS hps_client_window,
                           int width,
@@ -814,6 +854,31 @@ cairo_os2_surface_create (HPS hps_client_window,
     return (cairo_surface_t *)local_os2_surface;
 }
 
+/**
+ * cairo_os2_surface_set_size:
+ * @surface: the cairo surface to resize
+ * @new_width: the new width of the surface
+ * @new_height: the new height of the surface
+ * @timeout: timeout value in milliseconds
+ *
+ * When the client window is resized, call this API to set the new size in the
+ * underlying surface accordingly. This function will reallocate everything,
+ * so you'll have to redraw everything in the surface after this call.
+ * The surface will contain garbage after the resizing. So the notes of
+ * cairo_os2_surface_create() apply here, too.
+ *
+ * The timeout value specifies how long the function should wait on other parts
+ * of the program to release the buffers. It is necessary, because it can happen
+ * that Cairo is just drawing something into the surface while we want to
+ * destroy and recreate it.
+ *
+ * Return value: %CAIRO_STATUS_SUCCESS if the surface could be resized,
+ * %CAIRO_STATUS_SURFACE_TYPE_MISMATCH if the surface is not an OS/2 surface,
+ * %CAIRO_STATUS_NO_MEMORY if the new size could not be allocated, for invalid
+ * sizes, or if the timeout happened before all the buffers were released
+ *
+ * Since: 1.4
+ **/
 int
 cairo_os2_surface_set_size (cairo_surface_t *surface,
                             int              new_width,
@@ -921,6 +986,31 @@ cairo_os2_surface_set_size (cairo_surface_t *surface,
     return CAIRO_STATUS_SUCCESS;
 }
 
+/**
+ * cairo_os2_surface_refresh_window:
+ * @surface: the cairo surface to refresh
+ * @hps_begin_paint: the presentation handle of the window to refresh
+ * @prcl_begin_paint_rect: the rectangle to redraw
+ *
+ * This function can be used to force a repaint of a given area of the client
+ * window. It should usually be called from the WM_PAINT processing of the
+ * window procedure. However, it can be called any time a given part of the
+ * window has to be updated.
+ *
+ * The HPS and RECTL to be passed can be taken from the usual WinBeginPaint call
+ * of the window procedure, but you can also get the HPS using WinGetPS, and you
+ * can assemble your own update rectangle by hand.
+ * If hps_begin_paint is %NULL, the function will use the HPS passed into
+ * cairo_os2_surface_create(). If @prcl_begin_paint_rect is %NULL, the function
+ * will query the current window size and repaint the whole window.
+ *
+ * Cairo assumes that if you set the HWND to the surface using
+ * cairo_os2_surface_set_hwnd(), this function will be called by the application
+ * every time it gets a WM_PAINT for that HWND. If the HWND is set in the
+ * surface, Cairo uses this function to handle dirty areas too.
+ *
+ * Since: 1.4
+ **/
 void
 cairo_os2_surface_refresh_window (cairo_surface_t *surface,
                                   HPS              hps_begin_paint,
@@ -1018,6 +1108,28 @@ _cairo_os2_surface_finish (void *abstract_surface)
     return CAIRO_STATUS_SUCCESS;
 }
 
+/**
+ * cairo_os2_surface_set_hwnd:
+ * @surface: the cairo surface to associate with the window handle
+ * @hwnd_client_window: the window handle of the client window
+ *
+ * Sets window handle for surface. If Cairo wants to blit into the window
+ * because it is set to blit as the surface changes (see
+ * cairo_os2_surface_set_manual_window_refresh()), then there are two ways it
+ * can choose:
+ * If it knows the HWND of the surface, then it invalidates that area, so the
+ * application will get a WM_PAINT message and it can call
+ * cairo_os2_surface_refresh_window() to redraw that area. Otherwise cairo itself
+ * will use the HPS it got at surface creation time, and blit the pixels itself.
+ * It's also a solution, but experience shows that if this happens from a non-PM
+ * thread, then it can screw up PM internals.
+ *
+ * So, best solution is to set the HWND for the surface after the surface
+ * creation, so every blit will be done from application's message processing
+ * loop, which is the safest way to do.
+ *
+ * Since: 1.4
+ **/
 void
 cairo_os2_surface_set_hwnd (cairo_surface_t *surface,
                             HWND             hwnd_client_window)
@@ -1044,6 +1156,25 @@ cairo_os2_surface_set_hwnd (cairo_surface_t *surface,
     DosReleaseMutexSem (local_os2_surface->hmtx_use_private_fields);
 }
 
+/**
+ * cairo_os2_surface_set_manual_window_refresh:
+ * @surface: the cairo surface to set the refresh mode for
+ * @manual_refresh: the switch for manual surface refresh
+ *
+ * This API can tell Cairo if it should show every change to this surface
+ * immediately in the window or if it should be cached and will only be visible
+ * once the user calls cairo_os2_surface_refresh_window() explicitly. If the
+ * HWND was not set in the cairo surface, then the HPS will be used to blit the
+ * graphics. Otherwise it will invalidate the given window region so the user
+ * will get the WM_PAINT message to redraw that area of the window.
+ *
+ * So, if you're only interested in displaying the final result after several
+ * drawing operations, you might get better performance if you put the surface
+ * into manual refresh mode by passing a true value to this function. Then call
+ * cairo_os2_surface_refresh() whenever desired.
+ *
+ * Since: 1.4
+ **/
 void
 cairo_os2_surface_set_manual_window_refresh (cairo_surface_t *surface,
                                              cairo_bool_t     manual_refresh)
@@ -1061,6 +1192,14 @@ cairo_os2_surface_set_manual_window_refresh (cairo_surface_t *surface,
     local_os2_surface->blit_as_changes = !manual_refresh;
 }
 
+/**
+ * cairo_os2_surface_get_manual_window_refresh:
+ * @surface: the cairo surface to query the refresh mode from
+ *
+ * Return value: current refresh mode of the surface (true by default)
+ *
+ * Since: 1.4
+ **/
 cairo_bool_t
 cairo_os2_surface_get_manual_window_refresh (cairo_surface_t *surface)
 {
diff --git a/src/cairo-os2.h b/src/cairo-os2.h
index bd4d034f..97ab88ca 100644
--- a/src/cairo-os2.h
+++ b/src/cairo-os2.h
@@ -44,153 +44,38 @@ CAIRO_BEGIN_DECLS
 
 /* The OS/2 Specific Cairo API */
 
-/* cairo_os2_init () :                                              */
-/*                                                                  */
-/* Initializes the Cairo library. This function is automatically    */
-/* called if Cairo was compiled to be a DLL (however it's not a     */
-/* problem if it's called multiple times), but if you link to       */
-/* Cairo statically, you have to call it once to set up Cairo's     */
-/* internal structures and mutexes.                                 */
-
 cairo_public void
 cairo_os2_init (void);
 
-/* cairo_os2_fini () :                                              */
-/*                                                                  */
-/* Uninitializes the Cairo library. This function is automatically  */
-/* called if Cairo was compiled to be a DLL (however it's not a     */
-/* problem if it's called multiple times), but if you link to       */
-/* Cairo statically, you have to call it once to shut down Cairo,   */
-/* to let it free all the resources it has allocated.               */
-
 cairo_public void
 cairo_os2_fini (void);
 
 #if CAIRO_HAS_OS2_SURFACE
 
-/* cairo_os2_surface_create () :                                    */
-/*                                                                  */
-/* Create a Cairo surface which is bounded to a given presentation  */
-/* space (HPS). The surface will be created to have the given       */
-/* size.                                                            */
-/* By default: Every change to the surface will be made visible     */
-/*             immediately by blitting it into the window. This     */
-/*             can be changed with the                              */
-/*             cairo_os2_surface_set_manual_window_refresh () API.  */
-/* Note that the surface will contain garbage when created, so the  */
-/* pixels have to be initialized by hand first. You can use the     */
-/* Cairo functions to fill it with black, or use the                */
-/* cairo_surface_mark_dirty () API to fill the surface with pixels  */
-/* from the window/HPS.                                             */
-
 cairo_public cairo_surface_t *
 cairo_os2_surface_create (HPS hps_client_window,
                           int width,
                           int height);
 
-/* cairo_os2_surface_set_hwnd () :                                  */
-/*                                                                  */
-/* Sets window handle for surface. If Cairo wants to blit into the  */
-/* window because it's set that it should blit as the surface       */
-/* changes (see cairo_os2_surface_set_manual_window_refresh () API),*/
-/* then there are two ways it can choose:                           */
-/* If it knows the HWND of the surface, then it invalidates that    */
-/* area, so the application will get a WM_PAINT message and it can  */
-/* call cairo_os2_surface_refresh_window () to redraw that area.    */
-/* Otherwise cairo itself will use the HPS it got at surface        */
-/* creation time, and blit the pixels itself.                       */
-/* It's also a solution, but experience shows that if this happens  */
-/* from a non-PM thread, then it can screw up PM internals.         */
-/*                                                                  */
-/* So, best solution is to set the HWND for the surface after the   */
-/* surface creation, so every blit will be done from application's  */
-/* message processing loop, which is the safest way to do.          */
-
 cairo_public void
 cairo_os2_surface_set_hwnd (cairo_surface_t *surface,
                             HWND             hwnd_client_window);
 
-/* cairo_os2_surface_set_size () :                                  */
-/*                                                                  */
-/* When the client window is resized, call this API so the          */
-/* underlaying surface will also be resized. This function will     */
-/* reallocate everything, so you'll have to redraw everything in    */
-/* the surface after this call.                                     */
-/* The surface will contain garbage after the resizing, just like   */
-/* after cairo_os2_surface_create (), so all those notes also apply */
-/* here, please read that!                                          */
-/*                                                                  */
-/* The timeout value is in milliseconds, and tells how much the     */
-/* function should wait on other parts of the program to release    */
-/* the buffers. It is necessary, because it can be that Cairo is    */
-/* just drawing something into the surface while we want to         */
-/* destroy and recreate it.                                         */
-/* Returns %CAIRO_STATUS_SUCCESS if the surface could be resized,    */
-/* or returns other error code if                                   */
-/*  - the surface is not a real OS/2 Surface                        */
-/*  - there is not enough memory to resize the surface              */
-/*  - waiting for all the buffers to be released timed out          */
-
 cairo_public int
 cairo_os2_surface_set_size (cairo_surface_t *surface,
                             int              new_width,
                             int              new_height,
                             int              timeout);
 
-/* cairo_os2_surface_refresh_window () :                            */
-/*                                                                  */
-/* This function can be used to force a repaint of a given area     */
-/* of the client window. Most of the time it is called from the     */
-/* WM_PAINT processing of the window proc. However, it can be       */
-/* called anytime if a given part of the window has to be updated.  */
-/*                                                                  */
-/* The function expects a HPS of the window, and a RECTL to tell    */
-/* which part of the window should be redrawn.                      */
-/* The returned values of WinBeginPaint () is just perfect here,    */
-/* but you can also get the HPS by using the WinGetPS () function,  */
-/* and you can assemble your own update rect by hand.               */
-/* If the hps_begin_paint parameter is %NULL, the function will use  */
-/* the HPS you passed in to cairo_os2_surface_create (). If the     */
-/* prcl_begin_paint_rect parameter is %NULL, the function will query */
-/* the current window size and repaint the whole window.            */
-/*                                                                  */
-/* Cairo/2 assumes that if you told the HWND to the surface using   */
-/* the cairo_os2_surface_set_hwnd () API, then this function will   */
-/* be called by the application every time it gets a WM_PAINT for   */
-/* that HWND. If the HWND is told to the surface, Cairo uses this   */
-/* function to handle dirty areas too, so you were warned. :)       */
-
 cairo_public void
 cairo_os2_surface_refresh_window (cairo_surface_t *surface,
                                   HPS              hps_begin_paint,
                                   PRECTL           prcl_begin_paint_rect);
 
-/* cairo_os2_surface_set_manual_window_refresh () :                 */
-/*                                                                  */
-/* This API can tell Cairo if it should show every change to this   */
-/* surface immediately in the window, or if it should be cached     */
-/* and will only be visible if the user calls the                   */
-/* cairo_os2_surface_refresh_window () API explicitly.              */
-/* If the HWND was not told to Cairo, then it will use the HPS to   */
-/* blit the graphics. Otherwise it will invalidate the given        */
-/* window region so the user will get WM_PAINT to redraw that area  */
-/* of the window.                                                   */
-/*                                                                  */
-/* So, if you're only interested in displaying the final result     */
-/* after several drawing operations, you might get better           */
-/* performance if you  put the surface into a manual refresh mode   */
-/* by passing a true value to cairo_os2_surface_set_manual_refresh()*/
-/* and then calling cairo_os2_surface_refresh() whenever desired.   */
-
 cairo_public void
 cairo_os2_surface_set_manual_window_refresh (cairo_surface_t *surface,
                                              cairo_bool_t     manual_refresh);
 
-/* cairo_os2_surface_get_manual_window_refresh () :                 */
-/*                                                                  */
-/* This API can return the current mode of the surface. It is       */
-/* TRUE by default.                                                 */
-
 cairo_public cairo_bool_t
 cairo_os2_surface_get_manual_window_refresh (cairo_surface_t *surface);