[librsvg] Update deprecation documentation for the size_callback

[Federico Mena Quintero <federico src gnome org>]

commit c91854933e28c9c37f051ee1e2f7516a30a2a41b
Author: Federico Mena Quintero <federico gnome org>
Date:   Thu Jan 24 18:02:55 2019 -0600

    Update deprecation documentation for the size_callback

 librsvg/rsvg-handle.c | 35 ++++++++++++++++++++++++++---------
 librsvg/rsvg.h        | 27 +++++++++++++++++++--------
 2 files changed, 45 insertions(+), 17 deletions(-)
---
diff --git a/librsvg/rsvg-handle.c b/librsvg/rsvg-handle.c
index 0fb6beb1..937da4f4 100644
--- a/librsvg/rsvg-handle.c
+++ b/librsvg/rsvg-handle.c
@@ -1045,15 +1045,26 @@ rsvg_handle_set_dpi_x_y (RsvgHandle * handle, double dpi_x, double dpi_y)
  * @handle: An #RsvgHandle
  * @size_func: (nullable): A sizing function, or %NULL
  * @user_data: User data to pass to @size_func, or %NULL
- * @user_data_destroy: Destroy function for @user_data, or %NULL
- *
- * Sets the sizing function for the @handle.  This function is called right
- * after the size of the image has been loaded.  The size of the image is passed
- * in to the function, which may then modify these values to set the real size
- * of the generated pixbuf.  If the image has no associated size, then the size
- * arguments are set to -1.
- *
- * Deprecated: Set up a cairo matrix and use rsvg_handle_render_cairo() instead.
+ * @user_data_destroy: Function to be called to destroy the data passed in @user_data,
+ *   or %NULL.
+ *
+ * Sets the sizing function for the @handle, which can be used to override the
+ * size that librsvg computes for SVG images.  The @size_func is called from the
+ * following functions:
+ *
+ * <itemizedlist>
+ *   <listitem>rsvg_handle_get_dimensions()</listitem>
+ *   <listitem>rsvg_handle_get_dimensions_sub()</listitem>
+ *   <listitem>rsvg_handle_get_position_sub()</listitem>
+ *   <listitem>rsvg_handle_render_cairo()</listitem>
+ *   <listitem>rsvg_handle_render_cairo_sub()</listitem>
+ * </itemizedlist>
+ *
+ * Librsvg computes the size of the SVG being rendered, and passes it to the
+ * @size_func, which may then modify these values to set the final size of the
+ * generated image.
+ *
+ * Deprecated: 2.14.  Set up a cairo matrix and use rsvg_handle_render_cairo() instead.
  * You can call rsvg_handle_get_dimensions() to figure out the size of your SVG,
  * and then scale it to the desired size via Cairo.  For example, the following
  * code renders an SVG at a specified size, scaled proportionally from whatever
@@ -1079,6 +1090,12 @@ rsvg_handle_set_dpi_x_y (RsvgHandle * handle, double dpi_x, double dpi_y)
  *     rsvg_handle_render_cairo (handle, cr);
  * }
  * ]|
+ *
+ * This function was deprecated because when the @size_func is used, it makes it
+ * unclear when the librsvg functions which call the @size_func will use the
+ * size computed originally, or the callback-specified size, or whether it
+ * refers to the whole SVG or to just a sub-element of it.  It is easier, and
+ * unambiguous, to use code similar to the example above.
  **/
 void
 rsvg_handle_set_size_callback (RsvgHandle * handle,
diff --git a/librsvg/rsvg.h b/librsvg/rsvg.h
index ed5fd297..3ff6c4f1 100644
--- a/librsvg/rsvg.h
+++ b/librsvg/rsvg.h
@@ -190,13 +190,23 @@ gboolean rsvg_handle_has_sub (RsvgHandle * handle, const char *id);
 
 /**
  * RsvgHandleFlags:
- * @RSVG_HANDLE_FLAGS_NONE: none
- * @RSVG_HANDLE_FLAG_UNLIMITED: Allow any SVG XML without size limitations.
- *   For security reasons, this should only be used for trusted input!
+ * @RSVG_HANDLE_FLAGS_NONE: No flags are set.
+ * @RSVG_HANDLE_FLAG_UNLIMITED: Disable safety limits in the XML parser.
+ *   Libxml2 has <link
+ *   xlink:href="https://gitlab.gnome.org/GNOME/libxml2/blob/master/include/libxml/parserInternals.h";>several
+ *   limits</link> designed to keep malicious XML content from consuming too
+ *   much memory while parsing.  For security reasons, this should only be used
+ *   for trusted input!
  *   Since: 2.40.3
- * @RSVG_HANDLE_FLAG_KEEP_IMAGE_DATA: Keeps the image data when loading images,
- *  for use by cairo when painting to e.g. a PDF surface. This will make the
- *  resulting PDF file smaller and faster.
+ * @RSVG_HANDLE_FLAG_KEEP_IMAGE_DATA: Use this if the Cairo surface to which you
+ *  are rendering is a PDF, PostScript, SVG, or Win32 Printing surface.  This
+ *  will make librsvg and Cairo use the original, compressed data for images in
+ *  the final output, instead of passing uncompressed images.  This will make a
+ *  Keeps the image data when loading images, for use by cairo when painting to
+ *  e.g. a PDF surface.  For example, this will make the a resulting PDF file
+ *  smaller and faster.  Please see <link
+ *  
xlink:href="https://www.cairographics.org/manual/cairo-cairo-surface-t.html#cairo-surface-set-mime-data";>the
+ *  Cairo documentation</link> for details.
  *  Since: 2.40.3
  */
 typedef enum /*< flags >*/ 
@@ -252,8 +262,9 @@ void rsvg_handle_free (RsvgHandle * handle);
  *
  * Function to let a user of the library specify the SVG's dimensions
  *
- * Deprecated: Set up a cairo matrix and use rsvg_handle_render_cairo() instead.
- * See the documentation for rsvg_handle_set_size_callback() for an example.
+ * Deprecated: 2.14.  Set up a cairo matrix and use rsvg_handle_render_cairo() instead.
+ * See the documentation for rsvg_handle_set_size_callback() for an example, and
+ * for the reasons for deprecation.
  */
 /* RSVG_DEPRECATED */ typedef void (*RsvgSizeFunc) (gint * width, gint * height, gpointer user_data);