Update comments.

1 files changed, 32 insertions, 11 deletions

diff --git a/st_api.h b/st_api.h
index 7160e33..b5ecbfd 100644
--- a/st_api.h
+++ b/st_api.h
@@ -92,10 +92,16 @@ enum st_framebuffer_attachment {
 #define ST_FRAMEBUFFER_ACCUM_MASK       (1 << ST_FRAMEBUFFER_ACCUM)
 #define ST_FRAMEBUFFER_SAMPLE_MASK      (1 << ST_FRAMEBUFFER_SAMPLE)
 
+/**
+ * Enumerations of state tracker manager resources.
+ */
 enum st_manager_resource_type {
    ST_MANAGER_RESOURCE_EGL_IMAGE,   /* return struct pipe_texture */
 };
 
+/**
+ * Enumerations of state tracker context resources.
+ */
 enum st_context_resource_type {
    /* all of them return struct pipe_texture */
    ST_CONTEXT_RESOURCE_OPENGL_TEXTURE_2D,
@@ -110,10 +116,18 @@ enum st_context_resource_type {
    ST_CONTEXT_RESOURCE_OPENVG_PARENT_IMAGE,
 };
 
+/**
+ * The return type of st_api->get_proc_address.
+ */
+typedef void (*st_proc_t)(void);
+
 struct pipe_context;
 struct pipe_texture;
 struct pipe_fence_handle;
 
+/**
+ * Represent the visual of a framebuffer.
+ */
 struct st_visual
 {
    /**
@@ -162,12 +176,18 @@ struct st_framebuffer
     */
    void *st_manager_private;
 
+   /**
+    * The visual of a framebuffer.
+    */
    const struct st_visual *visual;
 
    /**
     * Flush the front buffer.
     *
-    * @att is either FRONT_LEFT or FRONT_RIGHT.
+    * On some window systems, changes to the front buffers are not immediately
+    * visible.  They need to be flushed.
+    *
+    * @att is one of the front buffer attachments.
     */
    boolean (*flush_front)(struct st_framebuffer *stfb,
                           enum st_framebuffer_attachment statt);
@@ -207,6 +227,9 @@ struct st_context
     */
    void *st_api_private;
 
+   /**
+    * Destroy the context.
+    */
    void (*destroy)(struct st_context *stctx);
 
    /**
@@ -244,9 +267,8 @@ struct st_context
    /**
     * Flush all drawing from context to the pipe also flushes the pipe.
     */
-   void (*flush)(struct st_context *stctx,
-                 unsigned pipe_flush_flags,
-                 struct pipe_fence_handle **fence);
+   void (*flush)(struct st_context *stctx, unsigned flags,
+		 struct pipe_fence_handle **fence);
 
    /**
     * Replace the texture image of a texture object at the specified level.
@@ -264,10 +286,6 @@ struct st_context
 		unsigned mask);
 };
 
-/**
- * Dummy function pointer used for get_proc_address.
- */
-typedef void (*st_proc_t)(void);
 
 /**
  * Represent a state tracker manager.
@@ -298,10 +316,13 @@ struct st_manager
  */
 struct st_api
 {
+   /**
+    * Destroy the API.
+    */
    void (*destroy)(struct st_api *stapi);
 
    /**
-    * Return a API entry point.
+    * Return an API entry point.
     *
     * For GL this is the same as _glapi_get_proc_address.
     */
@@ -327,7 +348,7 @@ struct st_api
                                         struct st_context *stshare);
 
    /**
-    * Bind the context to this thread with draw and read as drawables.
+    * Bind the context to the calling thread with draw and read as drawables.
     */
    boolean (*make_current)(struct st_api *stapi,
                            struct st_context *stctx,
@@ -335,7 +356,7 @@ struct st_api
                            struct st_framebuffer *stread);
 
    /**
-    * Get the currently bound context in this thread.
+    * Get the currently bound context in the calling thread.
     */
    struct st_context *(*get_current)(struct st_api *stapi);
 };