[librsvg: 2/5] Update docs for rsvg_handle_get_intrinsic_dimensions to take into accout geometry properties

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

commit b6766e3718e2e766f28e9c8c39cefc84fbcec1c2
Author: Federico Mena Quintero <federico gnome org>
Date:   Tue Mar 15 13:33:49 2022 -0600

    Update docs for rsvg_handle_get_intrinsic_dimensions to take into accout geometry properties
    
    Part-of: <https://gitlab.gnome.org/GNOME/librsvg/-/merge_requests/681>

 include/librsvg/rsvg.h | 29 ++++++++++++++++++++++-------
 1 file changed, 22 insertions(+), 7 deletions(-)
---
diff --git a/include/librsvg/rsvg.h b/include/librsvg/rsvg.h
index 6a09a7db2..d7e822ef4 100644
--- a/include/librsvg/rsvg.h
+++ b/include/librsvg/rsvg.h
@@ -837,26 +837,41 @@ typedef struct {
 /**
  * rsvg_handle_get_intrinsic_dimensions:
  * @handle: An [class@Rsvg.Handle]
- * @out_has_width: (out)(optional): Will be set to `TRUE` if the toplevel SVG has a `width` attribute
- * @out_width: (out)(optional): Will be set to the value of the `width` attribute in the toplevel SVG
- * @out_has_height: (out)(optional): Will be set to `TRUE` if the toplevel SVG has a `height` attribute
- * @out_height: (out)(optional): Will be set to the value of the `height` attribute in the toplevel SVG
+ * @out_has_width: (out)(optional): Will be set to `TRUE`; see below.
+ * @out_width: (out)(optional): Will be set to the computed value of the `width` property in the toplevel 
SVG.
+ * @out_has_height: (out)(optional): Will be set to `TRUE`; see below.
+ * @out_height: (out)(optional): Will be set to the computed value of the `height` property in the toplevel 
SVG.
  * @out_has_viewbox: (out)(optional): Will be set to `TRUE` if the toplevel SVG has a `viewBox` attribute
  * @out_viewbox: (out)(optional): Will be set to the value of the `viewBox` attribute in the toplevel SVG
  *
- * Queries the `width`, `height`, and `viewBox` attributes in an SVG document.
+ * In simple terms, queries the `width`, `height`, and `viewBox` attributes in an SVG document.
  *
  * If you are calling this function to compute a scaling factor to render the SVG,
  * consider simply using [method@Rsvg.Handle.render_document] instead; it will do the
  * scaling computations automatically.
  *
- * As an example, the following SVG element has a `width` of 100 pixels and a `height` of 400 pixels, but no 
`viewBox`:
+ * Before librsvg 2.54.0, the `out_has_width` and `out_has_height` arguments would be set to true or false
+ * depending on whether the SVG document actually had `width` and `height` attributes, respectively.
+ *
+ * However, since librsvg 2.54.0, `width` and `height` are now [geometry
+ * properties](https://www.w3.org/TR/SVG2/geometry.html) per the SVG2 specification; they
+ * are not plain attributes.  SVG2 made it so that the initial value of those properties
+ * is `auto`, which is equivalent to specifing a value of `100%`.  In this sense, even SVG
+ * documents which lack `width` or `height` attributes semantically have to make them
+ * default to `100%`.  This is why since librsvg 2.54.0, `out_has_width` and
+ * `out_has_heigth` are always returned as `TRUE`, since with SVG2 all documents *have* a
+ * default width and height of `100%`.
+ *
+ * As an example, the following SVG element has a `width` of 100 pixels and a `height` of 400 pixels, but no 
`viewBox`.  This
+ * function will return those sizes in `out_width` and `out_height`, and set `out_has_viewbox` to `FALSE`.
  *
  * ```
  * <svg xmlns="http://www.w3.org/2000/svg"; width="100" height="400">
  * ```
  *
- * Conversely, the following element has a `viewBox`, but no `width` or `height`:
+ * Conversely, the following element has a `viewBox`, but no `width` or `height`.  This function will
+ * set `out_has_viewbox` to `TRUE`, and it will also set `out_has_width` and `out_has_height` to `TRUE` but
+ * return both length values as `100%`.
  *
  * ```
  * <svg xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 100 400">