[cogl] doc: deprecate cogl_texture_get_rowstride()

[Robert Bragg <rbragg src gnome org>]

commit 757916f17a78e91c0af206e03e32b17f3a061542
Author: Robert Bragg <robert linux intel com>
Date:   Tue Nov 1 19:05:32 2011 +0000

    doc: deprecate cogl_texture_get_rowstride()
    
    This documents that cogl_texture_get_rowstride() is deprecated (or
    rather it was a mistake that the api was ever published) and also
    clarifies the rowstride argument documentation for
    cogl_texture_get_data() to explain how it's automatically calculated
    when 0 is passed to help avoid misleading people into thinking that
    cogl_texture_get_rowstride() is an appropriate way to get a valid
    rowstride for that.
    
    Reviewed-by: Neil Roberts <neil linux intel com>

 cogl/cogl-texture.h |   43 ++++++++++++++++++++++++++++++++++---------
 1 files changed, 34 insertions(+), 9 deletions(-)
---
diff --git a/cogl/cogl-texture.h b/cogl/cogl-texture.h
index ba54188..ed947de 100644
--- a/cogl/cogl-texture.h
+++ b/cogl/cogl-texture.h
@@ -261,9 +261,29 @@ cogl_texture_get_format (CoglTexture *texture);
  * cogl_texture_get_rowstride:
  * @texture a #CoglTexture pointer.
  *
- * Queries the rowstride of a cogl texture.
- *
- * Return value: the offset in bytes between each consequetive row of pixels
+ * Determines the bytes-per-pixel for the #CoglPixelFormat retrieved
+ * from cogl_texture_get_format() and multiplies that by the texture's
+ * width.
+ *
+ * <note>It's very unlikely that anyone would need to use this API to
+ * query the internal rowstride of a #CoglTexture which can just be
+ * considered an implementation detail. Actually it's not even useful
+ * internally since underlying drivers are free to use a different
+ * format</note>
+ *
+ * </note>This API is only here for backwards compatibility and
+ * shouldn't be used in new code. In particular please don't be
+ * mislead to pass the returned value to cogl_texture_get_data() for
+ * the rowstride, since you should be passing the rowstride you desire
+ * for your destination buffer not the rowstride of the source
+ * texture.</note>
+ *
+ * Return value: The bytes-per-pixel for the current format
+ *               multiplied by the texture's width
+ *
+ * Deprecated: 1.10: There's no replacement for the API but there's
+ *                   also no known need for API either. It was just
+ *                   a mistake that it was ever published.
  */
 unsigned int
 cogl_texture_get_rowstride (CoglTexture *texture);
@@ -318,15 +338,20 @@ cogl_texture_get_gl_texture (CoglTexture *texture,
  * cogl_texture_get_data:
  * @texture a #CoglTexture pointer.
  * @format: the #CoglPixelFormat to store the texture as.
- * @rowstride: the rowstride of @data or retrieved from texture if none is
- * specified.
- * @data: memory location to write contents of buffer, or %NULL if we're
- * only querying the data size through the return value.
+ * @rowstride: the rowstride of @data in bytes or pass 0 to calculate
+ *             from the bytes-per-pixel of @format multiplied by the
+ *             @texture width.
+ * @data: memory location to write the @texture's contents, or %NULL
+ * to only query the data size through the return value.
  *
  * Copies the pixel data from a cogl texture to system memory.
  *
- * Return value: the size of the texture data in bytes, or 0 if the texture
- *   is not valid
+ * <note>Don't pass the value of cogl_texture_get_rowstride() as the
+ * @rowstride argument, the rowstride should be the rowstride you
+ * want for the destination @data buffer not the rowstride of the
+ * source texture</note>
+ *
+ * Return value: the size of the texture data in bytes
  */
 int
 cogl_texture_get_data (CoglTexture *texture,