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

@@ -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.
+ * Determines the bytes-per-pixel for the #CoglPixelFormat retrieved
+ * from cogl_texture_get_format() and multiplies that by the texture's
+ * width.
  *
- * Return value: the offset in bytes between each consequetive row of pixels
+ * <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
+ * @rowstride: the rowstride of @data in bytes or pass 0 to calculate
- * specified.
+ *             from the bytes-per-pixel of @format multiplied by the
- * @data: memory location to write contents of buffer, or %NULL if we're
+ *             @texture width.
- * only querying the data size through the return value.
+ * @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
+ * <note>Don't pass the value of cogl_texture_get_rowstride() as the
- *   is not valid
+ * @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,