libnm-util: Fix transfer annotations of nm_{connection,setting}_need_secrets()

The various need_secrets() implementation do allocate a fresh GPtrArray, but
add static strings to them without dup'ing. Thus callers must _not_ free the
array elements, only the array itself. Adjust documentation and annotations
accordingly.

Also adjust the corresponding comment in the goi-list-connections.py example.

https://bugzilla.gnome.org/show_bug.cgi?id=698175

3 files changed, 10 insertions, 12 deletions

diff --git a/examples/python/goi-list-connections.py b/examples/python/goi-list-connections.py
index 10b93b8e89..1b617ae7b7 100755
--- a/examples/python/goi-list-connections.py
+++ b/examples/python/goi-list-connections.py
@@ -23,10 +23,8 @@ from gi.repository import GObject, NetworkManager, NMClient
 # This example asks settings service for all configured connections.
 # Unfortunately, at this time since libnm-glib still makes heavy use of
 # GValue and GHashTable (rather than GVariant), libnm-glib isn't fully
-# usable from GObject Introspection-ready languages.  Most functions will
-# work fine, but those involving connection secrets (like
-# nm_remote_connection_get_secrets() or nm_connection_to_hash()) cause assertion
-# failures since pygobject cannot handle complex GHashTable elements.
+# usable from GObject Introspection-ready languages. Most functions will
+# work fine, but e. g. nm_connection_to_hash() causes assertion failures.
 
 main_loop = None
 
diff --git a/libnm-util/nm-connection.c b/libnm-util/nm-connection.c
index dff7546aa1..c868bcd664 100644
--- a/libnm-util/nm-connection.c
+++ b/libnm-util/nm-connection.c
@@ -840,12 +840,12 @@ setting_priority_compare (gconstpointer a, gconstpointer b)
 /**
  * nm_connection_need_secrets:
  * @connection: the #NMConnection
- * @hints: (out callee-allocates) (element-type utf8) (allow-none) (transfer full):
- *   the address of a pointer to a #GPtrArray, initialized to NULL, which on
+ * @hints: (out) (element-type utf8) (allow-none) (transfer container):
+ *   the address of a pointer to a #GPtrArray, initialized to %NULL, which on
  *   return points to an allocated #GPtrArray containing the property names of
  *   secrets of the #NMSetting which may be required; the caller owns the array
- *   and must free the each array element with g_free(), as well as the array
- *   itself with g_ptr_array_free()
+ *   and must free the array itself with g_ptr_array_free(), but not free its
+ *   elements
  *
  * Returns the name of the first setting object in the connection which would
  * need secrets to make a successful connection.  The returned hints are only
diff --git a/libnm-util/nm-setting.c b/libnm-util/nm-setting.c
index d45f515583..9d245384d7 100644
--- a/libnm-util/nm-setting.c
+++ b/libnm-util/nm-setting.c
@@ -680,10 +680,10 @@ nm_setting_clear_secrets_with_flags (NMSetting *setting,
  * guide to what secrets may be required, because in some circumstances, there
  * is no way to conclusively determine exactly which secrets are needed.
  *
- * Returns: (transfer full) (element-type utf8): a #GPtrArray containing the property names of secrets of the
- * #NMSetting which may be required; the caller owns the array
- * and must free the each array element with g_free(), as well as the array
- * itself with g_ptr_array_free()
+ * Returns: (transfer container) (element-type utf8): a #GPtrArray containing
+ * the property names of secrets of the #NMSetting which may be required; the
+ * caller owns the array and must free it with g_ptr_array_free(), but must not
+ * free the elements.
  **/
 GPtrArray *
 nm_setting_need_secrets (NMSetting *setting)