[libgweather/drop-old-api: 3/7] Remove deprecated gweather_location_get_children()

[Emmanuele Bassi <ebassi src gnome org>]

commit 64699588c427433770b7a07c77bc5b7228e919f5
Author: Emmanuele Bassi <ebassi gnome org>
Date:   Fri Oct 15 16:44:05 2021 +0100

    Remove deprecated gweather_location_get_children()
    
    Add a paragraph in the porting guide on how to use the next_child()
    method.

 doc/migrating-3to4.md           | 25 +++++++++++++++++++
 libgweather/gweather-location.c | 53 -----------------------------------------
 libgweather/gweather-location.h |  3 ---
 3 files changed, 25 insertions(+), 56 deletions(-)
---
diff --git a/doc/migrating-3to4.md b/doc/migrating-3to4.md
index b0670615..d2c67ca9 100644
--- a/doc/migrating-3to4.md
+++ b/doc/migrating-3to4.md
@@ -11,3 +11,28 @@ GWeather 4 does not provide GTK widgets for selecting a location or a time
 zone. Applications should provide their own UI, if needed, according to the
 best practices of the [GNOME human interface
 guidelines](https://developer.gnome.org/hig/).
+
+### Stop using `gweather_location_get_children()`
+
+In order to iterate over the child locations of a [struct@GWeather.Location],
+you should use the iterator method [`method@GWeather.Location.next_child`]:
+
+```c
+/* Iterating using get_children() */
+GWeatherLocation **children = gweather_location_get_children (location);
+for (guint i = 0; children[i] != NULL; i++) {
+  GWeatherLocation *iter = children[i];
+  // ...
+}
+
+/* Iterating using next_child() */
+g_autoptr (GWeatherLocation) iter = NULL;
+while ((iter = gweather_location_next_child (location, iter)) != NULL) {
+  // ...
+}
+```
+
+**Note**: Unlike `gweather_location_get_children()`, the `next_child()`
+method will consume the reference of the iterated child; if you are keeping
+a reference to each child `GWeatherLocation` you should acquire a strong
+reference to it, using [method GWeather Location ref].
diff --git a/libgweather/gweather-location.c b/libgweather/gweather-location.c
index d59ac254..bccb80c7 100644
--- a/libgweather/gweather-location.c
+++ b/libgweather/gweather-location.c
@@ -577,59 +577,6 @@ invalid_child:
     return NULL;
 }
 
-/**
- * gweather_location_get_children:
- * @loc: a #GWeatherLocation
- *
- * Gets an array of @loc's children; this is owned by @loc and will
- * not remain valid if @loc is freed.
- *
- * Return value: (transfer none) (array zero-terminated=1): @loc's
- *   children. (May be empty, but will not be %NULL.)
- *
- * Deprecated: 40.0: Use gweather_location_next_child() instead to
- *   avoid high memory consumption
- **/
-GWeatherLocation **
-gweather_location_get_children (GWeatherLocation *loc)
-{
-    static GWeatherLocation *no_children = NULL;
-    DbArrayofuint16Ref children_ref;
-    gsize length;
-    gsize i;
-
-    g_return_val_if_fail (loc != NULL, &no_children);
-
-    if (loc->_children)
-       return loc->_children;
-
-    if (!loc->db)
-       return &no_children;
-
-    /* Fill in the magic nearest child if we need to and should. */
-    if (!g_getenv ("LIBGWEATHER_LOCATIONS_NO_NEAREST") &&
-        IDX_VALID (db_location_get_nearest (loc->ref))) {
-       loc->_children = g_new0 (GWeatherLocation*, 2);
-       loc->_children[0] = location_ref_for_idx (loc->db, db_location_get_nearest (loc->ref), loc);
-
-       return loc->_children;
-    }
-
-    /* Get the actual children. */
-    children_ref = db_location_get_children (loc->ref);
-    length = db_arrayofuint16_get_length (children_ref);
-    if (length == 0)
-       return &no_children;
-
-    loc->_children = g_new0 (GWeatherLocation*, length + 1);
-    for (i = 0; i < length; i++)
-       loc->_children[i] = location_ref_for_idx (loc->db,
-                                                db_arrayofuint16_get_at (children_ref, i),
-                                                NULL);
-
-    return loc->_children;
-}
-
 static void
 foreach_city (GWeatherLocation  *loc,
               GFunc              callback,
diff --git a/libgweather/gweather-location.h b/libgweather/gweather-location.h
index cce8a601..8d3b0570 100644
--- a/libgweather/gweather-location.h
+++ b/libgweather/gweather-location.h
@@ -112,9 +112,6 @@ GWEATHER_AVAILABLE_IN_ALL
 GWeatherLocation *      gweather_location_next_child            (GWeatherLocation  *loc,
                                                                  GWeatherLocation  *child);
 
-GWEATHER_DEPRECATED_FOR(gweather_location_next_child)
-GWeatherLocation **     gweather_location_get_children          (GWeatherLocation  *loc);
-
 GWEATHER_AVAILABLE_IN_ALL
 gboolean                gweather_location_has_coords            (GWeatherLocation  *loc);
 GWEATHER_AVAILABLE_IN_ALL