gallium: Comment on winsys's fence functions. Fix comment layout for doxygen.

src/mesa/pipe/p_winsys.h

@@ -42,6 +42,13 @@
 /** Opaque type for a buffer */
 struct pipe_buffer_handle;
 
+/** Opaque type */
+struct pipe_fence_handle;
+
+struct pipe_region;
+struct pipe_surface;
+
+
 /**
  * Gallium3D drivers are (meant to be!) independent of both GL and the
  * window system.  The window system provides a buffer manager and a
@@ -52,15 +59,6 @@ struct pipe_buffer_handle;
  * driver and the hardware driver about the format of command buffers,
  * etc.
  */
-
-
-struct pipe_region;
-struct pipe_surface;
-
-/** Opaque type */
-struct pipe_buffer_handle;
-struct pipe_fence_handle;
-
 struct pipe_winsys
 {
    /** Returns name of this winsys interface */
@@ -97,6 +95,7 @@ struct pipe_winsys
 
    void (*surface_release)(struct pipe_winsys *ws, struct pipe_surface **s);
 
+   
    /**
     * The buffer manager is modeled after the dri_bufmgr interface, which 
     * in turn is modeled after the ARB_vertex_buffer_object extension,  
@@ -115,7 +114,6 @@ struct pipe_winsys
                                                     void *ptr,
                                                     unsigned bytes);
 
-
    /** 
     * Map the entire data store of a buffer object into the client's address.
     * flags is bitmask of PIPE_BUFFER_FLAG_READ/WRITE. 
@@ -169,15 +167,29 @@ struct pipe_winsys
                              void *data);
 
 
+   /** Set ptr = buf, with reference counting */
    void (*fence_reference)( struct pipe_winsys *sws,
                             struct pipe_fence_handle **ptr,
                             struct pipe_fence_handle *fence );
 
+   /**
+    * Checks whether the fence has been signalled.
+    *  
+    * The meaning of flag is pipe-driver specific.
+    *
+    * Returns zero if it has.
+    */
    int (*fence_signalled)( struct pipe_winsys *sws,
                            struct pipe_fence_handle *fence,
                            unsigned flag );
 
-
+   /**
+    * Wait for the fence to finish.
+    * 
+    * The meaning of flag is pipe-driver specific.
+    * 
+    * Returns zero on success.
+    */
    int (*fence_finish)( struct pipe_winsys *sws,
                         struct pipe_fence_handle *fence,
                         unsigned flag );