Mesa (master): gbm: update documentation to reflect current behavior

[Kristian Høgsberg]

Module: Mesa
Branch: master
Commit: 55aab92495692f453c04f5b99e67bcb77cd27e14
URL:    http://cgit.freedesktop.org/mesa/mesa/commit/?id=55aab92495692f453c04f5b99e67bcb77cd27e14

Author: Ander Conselvan de Oliveira <ander.conselvan.de.oliveira at intel.com>
Date:   Mon Apr 30 13:27:52 2012 +0300

gbm: update documentation to reflect current behavior

---

 src/gbm/main/gbm.c |   18 ++++++++++--------
 1 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/src/gbm/main/gbm.c b/src/gbm/main/gbm.c
index c8e7ee7..0b5b9ff 100644
--- a/src/gbm/main/gbm.c
+++ b/src/gbm/main/gbm.c
@@ -389,10 +389,11 @@ gbm_surface_destroy(struct gbm_surface *surf)
  *
  * \param surf The surface
  *
- * \return A newly allocated buffer object that should be released
- * with gbm_surface_release_buffer() when no longer needed.  This bo
- * should not be destroyed using gbm_bo_destroy().  If an error occurs
- * this function returns %NULL.
+ * \return A buffer object that should be released with
+ * gbm_surface_release_buffer() when no longer needed.  The implementation
+ * is free to reuse buffers released with gbm_surface_release_buffer() so
+ * this bo should not be destroyed using gbm_bo_destroy().  If an error
+ * occurs this function returns %NULL.
  */
 GBM_EXPORT struct gbm_bo *
 gbm_surface_lock_front_buffer(struct gbm_surface *surf)
@@ -403,10 +404,11 @@ gbm_surface_lock_front_buffer(struct gbm_surface *surf)
 /**
  * Release a locked buffer obtained with gbm_surface_lock_front_buffer()
  *
- * The bo is destroyed after a call to this function and returns the
- * underlying buffer to the gbm surface.  Releasing a bo will
- * typically make gbm_surface_has_free_buffer() return 1 and thus
- * allow rendering the next frame, but not always.
+ * Returns the underlying buffer to the gbm surface.  Releasing a bo
+ * will typically make gbm_surface_has_free_buffer() return 1 and thus
+ * allow rendering the next frame, but not always. The implementation
+ * may choose to destroy the bo immediately or reuse it, in which case
+ * the user data associated with it is unchanged.
  *
  * \param surf The surface
  * \param bo The buffer object