[librsvg: 12/15] Mention API ordering restrictions for the get_pixbuf() functions

[Marge Bot <marge-bot src gnome org>]

commit 16a8d109b7219e714183d7b104a2165414ca31c4
Author: Federico Mena Quintero <federico gnome org>
Date:   Fri Sep 10 17:16:08 2021 -0500

    Mention API ordering restrictions for the get_pixbuf() functions
    
    Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/585>

 include/librsvg/rsvg.h | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)
---
diff --git a/include/librsvg/rsvg.h b/include/librsvg/rsvg.h
index 84ffa8d0..57fcd52f 100644
--- a/include/librsvg/rsvg.h
+++ b/include/librsvg/rsvg.h
@@ -622,15 +622,17 @@ gboolean rsvg_handle_close (RsvgHandle *handle, GError **error);
  * @handle: An #RsvgHandle
  *
  * Returns the pixbuf loaded by @handle.  The pixbuf returned will be reffed, so
- * the caller of this function must assume that ref.  If insufficient data has
- * been read to create the pixbuf, or an error occurred in loading, then %NULL
- * will be returned.  Note that the pixbuf may not be complete until
- * @rsvg_handle_close has been called.
+ * the caller of this function must assume that ref.
  *
- * This function depends on the #RsvgHandle's DPI to compute dimensions in
- * pixels, so you should call rsvg_handle_set_dpi() beforehand.
+ * API ordering: This function must be called on a fully-loaded @handle.  See
+ * the section <ulink url="RsvgHandle.html#API-ordering">API ordering</ulink> for details.
+ *
+ * This function depends on the #RsvgHandle's dots-per-inch value (DPI) to compute the
+ * "natural size" of the document in pixels, so you should call rsvg_handle_set_dpi()
+ * beforehand.
  *
- * Returns: (transfer full) (nullable): the pixbuf loaded by @handle, or %NULL.
+ * Returns: (transfer full) (nullable): a pixbuf, or %NULL if an error occurs
+ * during rendering.
  **/
 RSVG_API
 GdkPixbuf *rsvg_handle_get_pixbuf (RsvgHandle *handle);
@@ -647,8 +649,9 @@ GdkPixbuf *rsvg_handle_get_pixbuf (RsvgHandle *handle);
  * sub-sub-elements recursively).  If @id is #NULL, this function renders the
  * whole SVG.
  *
- * This function depends on the #RsvgHandle's DPI to compute dimensions in
- * pixels, so you should call rsvg_handle_set_dpi() beforehand.
+ * This function depends on the #RsvgHandle's dots-per-inch value (DPI) to compute the
+ * "natural size" of the document in pixels, so you should call rsvg_handle_set_dpi()
+ * beforehand.
  *
  * If you need to render an image which is only big enough to fit a particular
  * sub-element of the SVG, consider using rsvg_handle_render_element().
@@ -657,6 +660,9 @@ GdkPixbuf *rsvg_handle_get_pixbuf (RsvgHandle *handle);
  * "##foo" (hash <literal>foo</literal>) to get the geometry of the element that
  * has an <literal>id="foo"</literal> attribute.
  *
+ * API ordering: This function must be called on a fully-loaded @handle.  See
+ * the section <ulink url="RsvgHandle.html#API-ordering">API ordering</ulink> for details.
+ *
  * Returns: (transfer full) (nullable): a pixbuf, or %NULL if an error occurs
  * during rendering.
  *