[librsvg: 1/15] (#669): Document that intrinsic_size_in_pixels returns floats

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

commit 65ce8f115002c0112d17c134e8e70ddae006f434
Author: Federico Mena Quintero <federico gnome org>
Date:   Wed Jun 23 18:49:43 2021 -0500

    (#669): Document that intrinsic_size_in_pixels returns floats
    
    Fixes https://gitlab.gnome.org/GNOME/librsvg/-/issues/669
    
    Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/585>

 include/librsvg/rsvg.h | 12 ++++++++----
 src/api.rs             |  5 +++++
 2 files changed, 13 insertions(+), 4 deletions(-)
---
diff --git a/include/librsvg/rsvg.h b/include/librsvg/rsvg.h
index 80005887..fd6bd5d2 100644
--- a/include/librsvg/rsvg.h
+++ b/include/librsvg/rsvg.h
@@ -892,8 +892,8 @@ void rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle,
 /**
  * rsvg_handle_get_intrinsic_size_in_pixels:
  * @handle: An #RsvgHandle
- * @out_width: (out)(optional): Will be set to the computed width
- * @out_height: (out)(optional): Will be set to the computed height
+ * @out_width: (out)(optional): Will be set to the computed width; you should round this up to get integer 
pixels.
+ * @out_height: (out)(optional): Will be set to the computed height; you should round this up to get integer 
pixels.
  *
  * Converts an SVG document's intrinsic dimensions to pixels, and returns the result.
  *
@@ -939,8 +939,12 @@ void rsvg_handle_get_intrinsic_dimensions (RsvgHandle *handle,
  *
  *
  * Returns: %TRUE if the dimensions could be converted directly to pixels; in this case
- * @out_width and @out_height will be set accordingly.  If the dimensions cannot be converted
- * to pixels, returns %FALSE and puts 0.0 in both @out_width and @out_height.
+ * @out_width and @out_height will be set accordingly.  Note that the dimensions are
+ * floating-point numbers, so your application can know the exact size of an SVG document.
+ * To get integer dimensions, you should use `ceil()` to round up to the nearest integer
+ * (just using `round()`, may may chop off pixels with fractional coverage).  If the
+ * dimensions cannot be converted to pixels, returns %FALSE and puts 0.0 in both
+ * @out_width and @out_height.
  *
  * Since: 2.52
  */
diff --git a/src/api.rs b/src/api.rs
index c3837332..d0795972 100644
--- a/src/api.rs
+++ b/src/api.rs
@@ -355,6 +355,11 @@ impl<'a> CairoRenderer<'a> {
     /// `height` attributes with physical dimensions (CSS pixels, cm, in, etc.) or
     /// font-based dimensions (em, ex).
     ///
+    /// Note that the dimensions are floating-point numbers, so your application can know
+    /// the exact size of an SVG document.  To get integer dimensions, you should use
+    /// [`f64::ceil()`] to round up to the nearest integer (just using [`f64::round()`],
+    /// may may chop off pixels with fractional coverage).
+    ///
     /// If the SVG document has percentage-based `width` and `height` attributes, or if
     /// either of those attributes are not present, returns `None`.  Dimensions of that
     /// kind require more information to be resolved to pixels; for example, the calling